{{Header}}
{{title|title=
Configuration Files
}}
{{#seo:
|description=Everything you should know about Configuration Drop-in Folders and Files.
|image=Five-elements-379106640.jpg
}}
[[File:Five-elements-379106640.jpg|thumb]]
{{intro|
Everything you should know about Configuration Drop-in Folders and Files.
}}
{{Anchor|.d Style Configuration Folders}}
= Introduction =

When changing any configurations, it is recommended to use configuration drop-in folders whenever available to avoid the [[#Ordinary_Configuration_Files|disadvantages of ordinary configuration files]]. Using a configuration drop-in folder means "dropping a configuration snippet", which involves creating a new configuration file in a configuration drop-in folder.

This applies to most, if not all, other (Debian-based) Linux distributions, including {{project_name_long}}.

= Configuration Drop-In Folders =

[https://github.com/{{project_name_short}} Most] [[Debian Packages|{{project_name_short}} packages]] provide configuration drop-in folders:

* <code>/etc/systemcheck.d</code>
* <code>/etc/{{project_name_short_lowercase}}_firewall.d</code>
* <code>/etc/{{project_name_short_lowercase}}_buildconfig.d</code> (Only if you build from source code.)
* <code>/etc/sdwdate.d</code>
* <code>/etc/sdwdate-gui.d</code>
* <code>/etc/uwt.d</code>
* <code>/etc/onion-grater-merger.d</code>
* <code>/etc/torbrowser.d</code>
* <code>[[#/usr/local/etc|/usr/local/etc]]/torbrowser.d</code>

Note that Tor's configuration is a special case; see [[Tor#Configuration|here]] for further details.

To explain this concept, consider the [[sdwdate]] example. <code>/etc/sdwdate.d/30_default.conf</code> states:

<blockquote>Please use "/etc/sdwdate.d/50_user.conf" for your custom configuration,
which will override the defaults found here. When {{project_name_short}} is updated, this
file may be overwritten.
</blockquote>

The same message is described elsewhere as follows.

<blockquote>
Instead of editing this file, please create and use the file
"/etc/sdwdate.d/50_user.conf". When {{project_name_short}} is updated,
"/etc/sdwdate.d/30_default.conf" will be overwritten. Files in folder
"/etc/sdwdate.d/" are sourced in alphabetical order. Anything in
"/etc/sdwdate.d/50_user.conf" will always override the defaults,
allowing the user to keep their settings after updating {{project_name_short}}.</blockquote>

In simple terms, files in configuration drop-in folders are usually processed in alphabetical (lexical) order. That means files named <code>30_...</code> will always be overruled by files named <code>50_...</code>.

In this example, directly editing <code>/etc/sdwdate.d/30_default.conf</code> is recommended against. This is because the next time {{project_name_short}} is updated, <code>/etc/sdwdate.d/30_default.conf</code> may include new and improved settings. This would cause a {{Code2|dpkg interactive conflict resolution dialog}}, as shown below.

<pre>
Configuration file `/etc/sdwdate.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
</pre>

Modifications introduced by {{project_name_short}} will always fall back to reasonable defaults if you are still using an old version. However, to avoid such conflicts in the first place, it's better to:

* read <code>/etc/sdwdate.d/30_default.conf</code>
* leave <code>/etc/sdwdate.d/30_default.conf</code> untouched
* copy the settings you want to override from <code>/etc/sdwdate.d/30_default.conf</code> and paste them into <code>/etc/sdwdate.d/50_user.conf</code>

Since configuration drop-in folders are not standardized, drop-in snippets are processed differently depending on the software. Examples of these differences include:

* Some allow overriding configuration variables from earlier files in lexical order, such as <code>/etc/default/grub.d</code> (for grub configuration). Others do not, like <code>/etc/apt/sources.list.d</code> (APT repository definitions) or <code>/etc/apt/trusted.gpg.d</code> (APT signing keys).
* Some are <code>source</code>ed <ref>
<code>source</code>ed as in:

* <code>bash</code> <code>source</code>, or
* <code>sh</code> (shell script) <code>.</code> (same as <code>bash</code> <code>source</code>).

https://superuser.com/questions/46139/what-does-source-do
</ref> in lexical order, such as <code>/etc/profile.d</code> or <code>/etc/X11/Xsession.d</code>.
* Some contain scripts that are executed, such as <code>/etc/grub.d</code> (used for generating the GRUB boot menu).

= Ordinary Configuration Files =

Sometimes, a special configuration folder (called a "drop-in folder") is not available. In those cases, you must edit the main configuration files directly. This applies to {{project_name_short}} and most other Debian-based Linux systems.

Here is an example using the <code>/etc/hdparm.conf</code> file:

* <u>Absence of [[#Configuration Drop-In Folders|Configuration Drop-In Folder]]:</u> No <code>/etc/hdparm.d</code> folder is available
* <u>Ordinary configuration file:</u> Any changes must be made directly to <code>/etc/hdparm.conf</code>
* <u>Editing conflict:</u> Changing this file has a downside -- if the <code>hdparm</code> package is updated later, you may see a {{Code2|dpkg interactive conflict resolution dialog}} like the one below

{{anchor_link|dpkg interactive conflict resolution dialog}}

<pre>
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
</pre>

Always check the version differences (<code>D</code>) before choosing. If you made important changes to the file, you'll probably want to keep them by selecting <code>N</code>. If you're unsure, let the upgrade finish, then review the configuration file and reapply your changes if needed.

This configuration file is probably Open Source, so you can usually find the original version online. That can help when comparing versions. See [[Please Use Search Engines And See Documentation First]].

To compare your version with the original one provided by the package, you can use [[Software#File_Comparison_Tools|File Comparison Tools]].

= /usr/local/etc =

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

Placing configuration files in <code>/usr/local</code> 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 {{project_name_short}} support configuration files in the <code>/usr/local/application-name'''.d'''</code> folder. Other applications using configuration files in the <code>/usr/local</code> folder are unknown.

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

Configuration of Tor is a special case; see [[Tor#Configuration|Tor configuration]] for further information.

= Reset Configuration Files to Vendor Default =

It is possible to reset configuration files to vendor defaults. This is useful if a user changes their mind or selected the wrong action <ref>For example, not installed instead of installed.</ref> in response to a [[Operating_System_Software_and_Updates#Changed_Configuration_Files|Changed Configuration File]].

{{Box|text=
'''1.''' Check using <code>debsums</code>.

Run [https://manpages.debian.org <code>debsums</code>] to show a list of changed and missing configuration files.

{{CodeSelect|code=
sudo debsums -ce
}}

A sample output might look like this.

<pre>
sdwdate: /etc/sdwdate.d/30_default.conf
</pre>

This means:

<pre>
package-name: changed-configuration-file
</pre>

'''2.''' Reinstall the package.

In the command below, replace <code>package-name</code> with the actual name of the package, such as <code>sdwdate</code>. <ref>
[https://github.com/{{project_name_short}}/usability-misc/blob/master/usr/bin/apt-get-reset <code>apt-get-reset</code>] is a {{project_name_short}}-specific feature. It performs an action like this:

{{CodeSelect|code=
sudo apt -o Dpkg::Options::=--force-confnew,confmiss install --reinstall package-name
}}
</ref>

{{CodeSelect|code=
sudo apt-get-reset package-name
}}

The output will be similar to below.

<pre>
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.
</pre>

'''3.''' Re-check using <code>debsums</code>.

Re-run <code>sudo debsums -ce</code> to confirm the correct configuration files were changed as intended.
}}

= Commenting Syntax and Effects =

* <code>#</code> at the beginning of a line indicates a comment. Comment lines have no effect.
* Lines without a leading <code>#</code> are active and take effect.
* '''Commenting out''' means adding a <code>#</code> at the beginning of a line to disable it.
* '''Commenting in''' means removing a leading <code>#</code> from a line to enable it.
* In most cases, <code>#</code> is used for comments. In some applications, other symbols might be used instead. The correct commenting character can usually be determined by reading the configuration file.

= Systemd Configuration =
== Disable Systemd Drop-Ins ==
This is an example. Adjust as needed.

'''1.''' Create the override directory:

{{CodeSelect|code=
sudo mkdir -p /etc/systemd/system/openvpn@openvpn.service.d/
}}

'''2.''' Disable the specific drop-in file by linking it to <code>/dev/null</code>:

{{CodeSelect|code=
sudo ln -sf /dev/null /etc/systemd/system/openvpn@openvpn.service.d/50_unpriv.conf
}}

'''3.''' Done.

= Move Files Out of the Way =
This wiki chapter explains how to safely move system-managed files "out of the way" using [http://manpages.debian.org/dpkg-divert <code>dpkg-divert</code>] so they aren't overwritten during package updates. It includes identifying package ownership, checking file existence, moving files, and optionally undoing the diversion and restoring the original file.

<code>dpkg-divert</code> is a standard Debian tool. [[Based on Debian|{{project_name_short}} is based on Debian]]. This process is [[Unspecific|unspecific to {{project_name_short}}]]. The [[Self Support First Policy]] applies.

'''1.''' Create folder.

This is the folder where the files will be moved.

{{CodeSelect|code=
sudo mkdir --parents /var/lib/user
}}

'''2.''' Learn which package owns the file.

Syntax:

<pre>
dpkg -S /path/to/file/to/move/out/of/the/way
</pre>

Example:

{{CodeSelect|code=
dpkg -S /usr/lib/systemd/system/openvpn@openvpn.service.d/50_unpriv.conf
}}

'''3.''' Learn the syntax for file diversion.

<u>Note:</u> Do not run this command yet.

<pre>
sudo dpkg-divert --divert /path/to/new/file/location --rename /path/to/file/to/move/out/of/the/way
</pre>

'''4.''' Check if the file exists.

Syntax:

<pre>
ls /path/to/file/to/move/out/of/the/way
</pre>

Example:

<u>Note:</u> Adjust paths for your use case.

{{CodeSelect|code=
ls /usr/lib/systemd/system/openvpn@openvpn.service.d/50_unpriv.conf
}}

'''5.''' Example of diverting the file.

<u>Note:</u> Adjust paths for your use case.

{{CodeSelect|code=
sudo dpkg-divert --divert /var/lib/user/50_unpriv.conf --rename /usr/lib/systemd/system/openvpn@openvpn.service.d/50_unpriv.conf
}}

'''6.''' Confirm the file has been moved.

'''7.''' Done.

'''8.''' Undo DPKG diversion.

Syntax:

<pre>
sudo dpkg-divert --no-rename --remove /path/to/file/to/restore
</pre>

Example:

{{CodeSelect|code=
sudo dpkg-divert --no-rename --remove /usr/lib/systemd/system/openvpn@openvpn.service.d/50_unpriv.conf
}}

'''9.''' Restore the file.

Reinstall the package as per [[Install_Software#Re-Install_Package|Re-Install Package]] or even as per [[Configuration_Files#Reset_Configuration_Files_to_Vendor_Default|Reset Configuration Files to Vendor Default]].

= Platform Specific =
== Kicksecure ==
No special notice.

== Qubes Persistence ==

In the Qubes Template model, <ref>
[https://www.qubes-os.org/doc/getting-started/ App Qubes and Templates].</ref> any changes made to a [https://github.com/QubesOS/qubes-issues/issues/2489 root filesystem of an App Qube] 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 <code>/rw</code>, including <code>/home/user</code> and <code>/usr/local</code> as well as additional directories defined by "bind directory" settings. <ref>[https://www.qubes-os.org/doc/bind-dirs/ How to make any file in an App Qube persistent using bind-dirs].
</ref>

{{Qubes_persistence}}

Refer to the following advice when editing configuration files in {{q_project_name_long}}.

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

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

= Technical Information =
For advanced users only.

Most configuration files in Debian are handled by <code>dpkg</code>. Evidence for that is in <code>dpkg</code> source code file <code>src/configure.c</code>. <ref>
outdated github mirror: https://github.com/endlessm/dpkg/blob/master/src/configure.c
</ref>

<pre>
fprintf(stderr,
	        _("   What would you like to do about it ?  Your options are:\n"
	          "    Y or I  : install the package maintainer's version\n"
	          "    N or O  : keep your currently-installed version\n"
	          "      D     : show the differences between the versions\n"
	          "      Z     : start a shell to examine the situation\n"));
</pre>

Sometimes configuration files in Debian are handled by [https://packages.debian.org/sid/ucf <code>ucf</code>].

= See Also=
* [https://www.freedesktop.org/software/systemd/man/modules-load.d.html Configuration Directories and Precedence] explanation
* [[grub|Grub]] configuration changes
* [[Operating_System_Software_and_Updates#Changed_Configuration_Files|Changed Configuration Files]] during [[Operating System Software and Updates|Upgrades]]
* [[Debian Packages|{{project_name_short}} Debian Packages]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]