From 56863c21e155b31489e9c502b4307fa4a2a3deae Mon Sep 17 00:00:00 2001 From: unman Date: Mon, 20 Mar 2017 23:33:24 +0000 Subject: [PATCH] Clarified bind-dirs in accordance with comments in 299 --- customization/bind-dirs.md | 57 +++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 22 deletions(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index 77ce2cba..06280d99 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -8,14 +8,19 @@ redirect_from: # How to make any file in a TemplateBasedVM persistent using bind-dirs # -## What is bind-dirs.sh? ## +## What is bind-dirs? ## -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. +With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh) +any arbitrary files or folders can be made 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. +In a TemplateBasedVM all of the file system comes from the template except /home and /usr/local. +This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown. +bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots. + +For example, in Whonix, [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). +In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM. ## Minimum Qubes Version ## @@ -29,26 +34,18 @@ Inside your TemplateBasedVM. sudo mkdir -p /rw/config/qubes-bind-dirs.d -2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a VM. +2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights inside a TemplateBasedVM. - sudo nano /rw/config/qubes-bind-dirs.d/50_user.conf - -3. 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 of your choice. - - binds+=( '/var/lib/tor' ) - -In the following example we are using file `/etc/tor/torrc`. You can replace that file with a file of your choice. - - binds+=( '/etc/tor/torrc' ) - -Multiple configuration lines, files and folders supported. For example, you could use both. +3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable. (In the following example we are using folder `/var/lib/tor`. You can replace that name with a folder or file name of your choice.) binds+=( '/var/lib/tor' ) binds+=( '/etc/tor/torrc' ) +Multiple entries are possible, each on a separate line. + 4. Save. -5. Reboot your TemplateBasedVM. +5. Reboot the TemplateBasedVM. 6. Done. @@ -60,16 +57,32 @@ If you added for example folder `/var/lib/tor` to the `binds` variable, from now * `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration) * `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration) +## How does it work? ## + +bind-dirs.sh is called on startup of a TemplateBasedVM, and configuration files in the configuration folders above are parsed to build a bash array. +Files or folders identified in the array are copied to /rw/bind-dirs if they do not already exist there, and are then bind mounted over the original files/folders. + +Creation of the file and folders in /rw/bind-dirs should be automatic the first time the TemplateBasedVM is restarted after configuration. + +If you want to circumvent this process, you can create the relevant filestructure under /rw/bind-dirs and make any changes at the same time that you perform the configuration, before reboot. + + ## Limitations ## -* Files that exist in the TemplateVM root image cannot be made deleted in the TemplateBasedVMs 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. +* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh. +* The file / folder in question must 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 a 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. +* Many editors create a temporary file and copy it over the original file. If you have bind mounted an individual file this will break the mount. +Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs.rather than the file, or perform the file operation on the file in /rw/bind-dirs. +* Some files are altered when a qube boots - e.g. /etc/hosts. If you try to use bind-dirs on such files you may break your qube in unpredictable ways. + ## 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-persistent 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. +`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`