From 9e8daab5631f7a93e9205cb9a7d4f2aff5cdf7d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 13:37:06 +0200 Subject: [PATCH 1/6] 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 =================================== From fcdfccf722c9ec737aecaea602e9207c86dc2704 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 14:11:56 +0200 Subject: [PATCH 2/6] bind-dirs: adjust title --- configuration/bind-dirs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/bind-dirs.md b/configuration/bind-dirs.md index 62a89fc9..94341e64 100644 --- a/configuration/bind-dirs.md +++ b/configuration/bind-dirs.md @@ -1,6 +1,6 @@ --- layout: doc -title: Bind-dirs - make persisnent changes to arbitrary system file in AppVM +title: How to make any file in a TemplateBasedVM persistent using bind-dirs permalink: /doc/bind-dirs/ redirect_from: - /en/doc/bind-dirs/ From 437ea386d5b58ffdd21d2d76d654bc9d362bdd11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Thu, 15 Sep 2016 14:13:21 +0200 Subject: [PATCH 3/6] bind-dirs: move to customization, add to main index --- {configuration => customization}/bind-dirs.md | 0 doc.md | 1 + 2 files changed, 1 insertion(+) rename {configuration => customization}/bind-dirs.md (100%) diff --git a/configuration/bind-dirs.md b/customization/bind-dirs.md similarity index 100% rename from configuration/bind-dirs.md rename to customization/bind-dirs.md diff --git a/doc.md b/doc.md index c7f7fca4..6c691225 100644 --- a/doc.md +++ b/doc.md @@ -152,6 +152,7 @@ Customization Guides * [Installing i3 in dom0](/doc/i3/) * [Language Localization](/doc/language-localization/) * [Dark Theme in Dom0 and DomU](/doc/dark-theme/) + * [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/) Troubleshooting From f1e091e1460a56b0934379e529454ac956a9f456 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:14:38 -0700 Subject: [PATCH 4/6] Add title and fix heading levels --- customization/bind-dirs.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index 94341e64..7a8a1eb7 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -6,20 +6,22 @@ redirect_from: - /en/doc/bind-dirs/ --- -# What is bind-dirs.sh? # +# How to make any file in a TemplateBasedVM persistent using 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? # +## 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 # +## Minimum Qubes Version ## bind-dirs.sh works with Qubes R3.2 and above. -# How to use bind-dirs.sh? # +## 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. @@ -35,20 +37,20 @@ binds+=( '/var/lib/tor' ) 5) Done. -# Other Configuration Folders # +## 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 # +## 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? # +## 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. @@ -60,7 +62,7 @@ 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 # +## 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) From ed11064a60370774b3323ce102ae3e377469a0d0 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:20:30 -0700 Subject: [PATCH 5/6] Fix Markdown formatting --- customization/bind-dirs.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index 7a8a1eb7..c244e7ad 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -23,19 +23,17 @@ 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. +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. +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' ) -``` + binds+=( '/var/lib/tor' ) -3) Save. +3. Save. -4) Reboot the VM. +4. Reboot the VM. -5) Done. +5. Done. ## Other Configuration Folders ## @@ -56,9 +54,9 @@ binds+=( '/var/lib/tor' ) `/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.) From 28ec0003414dfc7553e993a0867169ee90214dbe Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Sep 2016 13:21:04 -0700 Subject: [PATCH 6/6] Fix discussion link --- customization/bind-dirs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customization/bind-dirs.md b/customization/bind-dirs.md index c244e7ad..c4074994 100644 --- a/customization/bind-dirs.md +++ b/customization/bind-dirs.md @@ -62,5 +62,5 @@ binds=( "${binds[@]/'/var/lib/tor'}" ) ## 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) +[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)