From 9e8daab5631f7a93e9205cb9a7d4f2aff5cdf7d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Thu, 15 Sep 2016 13:37:06 +0200
Subject: [PATCH] Add bind dirs documentation

Fixes QubesOS/qubes-issues#2315
---
 configuration/bind-dirs.md    | 66 +++++++++++++++++++++++++++++++++++
 configuration/config-files.md |  3 ++
 2 files changed, 69 insertions(+)
 create mode 100644 configuration/bind-dirs.md

diff --git a/configuration/bind-dirs.md b/configuration/bind-dirs.md
new file mode 100644
index 00000000..62a89fc9
--- /dev/null
+++ b/configuration/bind-dirs.md
@@ -0,0 +1,66 @@
+---
+layout: doc
+title: Bind-dirs - make persisnent changes to arbitrary system file in AppVM
+permalink: /doc/bind-dirs/
+redirect_from:
+- /en/doc/bind-dirs/
+---
+
+# What is bind-dirs.sh? #
+
+With [bind-dirs.sh](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
+you can make arbitrary files or folders persistent in TemplateBasedVMs.
+
+# What is it useful for? #
+
+For example, it is useful for Whonix, sys-whonix, where [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). So sys-whonix does not require to be a StandaloneVM. And therefore can benefit from the Tor anonymity feature 'persistent Tor entry guards' without the overhead of a StandaloneVM.
+
+# Minimum Qubes Version #
+
+bind-dirs.sh works with Qubes R3.2 and above.
+
+# How to use bind-dirs.sh? #
+
+1) Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM.
+
+2) Append a folder or file to the `binds` variable. In the following example we are using folder `/var/lib/tor`. You can replace that folder with a folder or file of your choice.
+
+```
+binds+=( '/var/lib/tor' )
+```
+
+3) Save.
+
+4) Reboot the VM.
+
+5) Done.
+
+# Other Configuration Folders #
+
+* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
+* `/etc/qubes-bind-dirs.d`  (intermediate priority, for template wide configuration)
+* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
+
+# Limitations #
+
+* Files that exist in the TempalteVM root image cannot be made deleted in the TemlateBasedVMs root image using bind-dirs.sh.
+* Does not work if the file / folder in question does not already exist in the root image. I.e. a file that does not exist in the root image cannot be bind mounted in the TemplateBasedVM.
+* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work.
+* Running 'sudo /usr/lib/qubes/bind-dirs.sh umount' after boot (before shutdown) is probably not sane and nothing can be done about that.
+
+# How to remove binds from bind-dirs.sh? #
+
+`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are `source`d as bash snippets in lexical order. Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file. For example, if you wanted to make `/var/lib/tor` non-persistant in `sys-whonix` without manually editing [`/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`](https://github.com/Whonix/qubes-whonix/blob/master/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf), you could use the following.
+
+`/rw/config/qubes-bind-dirs.d/50_user.conf`
+
+```
+binds=( "${binds[@]/'/var/lib/tor'}" )
+```
+
+(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is recommended against, since such changes get lost when that file is changed in the package on upgrades.)
+
+# Discussion #
+
+[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!searchin/qubes-devel/bind-dirs|sort:relevance/qubes-devel/tcYQ4eV-XX4/J89DRLzOBQAJ)
+
diff --git a/configuration/config-files.md b/configuration/config-files.md
index 43485c5a..388a1cb4 100644
--- a/configuration/config-files.md
+++ b/configuration/config-files.md
@@ -40,6 +40,9 @@ problematic device drivers.
 
 Note that scripts need to be executable (chmod +x) to be used.
 
+Also take a look at [bind-dirs][/doc/bind-dirs] for instruction how to easily
+modify arbitrary system file in AppVM and have those changes persistent.
+
 GUI and audio configuration in dom0
 ===================================