Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Tidied up bind-dirs.md

Browse Source 
Moved example to config-files.md
This commit is contained in:
unman 2019-06-06 16:35:08 +00:00
parent 224579e695
commit 6f1d018605
No known key found for this signature in database
GPG Key ID: BB52274595B71262
2 changed files with 32 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
user/advanced-configuration/bind-dirs.md
View File

@ -19,32 +19,38 @@ In a TemplateBasedVM all of the file system comes from the template except `/hom
This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown. 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. 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). For example, in Whonix, [Tor's data dir /var/lib/tor has been made persistent in the TemplateBased ProxyVM sys-whonix][whonix]
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM. In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## How to use bind-dirs.sh? ## ## How to use bind-dirs.sh? ##
Inside your TemplateBasedVM. In this example, we want to make /var/lib/tor persistent.
Inside the TemplateBasedVM.
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists. 1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
sudo mkdir -p /rw/config/qubes-bind-dirs.d 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 TemplateBasedVM. 2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights.
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.) 3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable.
binds+=( '/var/lib/tor' ) binds+=( '/var/lib/tor' )
Multiple entries are possible, each on a separate line.
4. Save. 4. Save.
5. Reboot the TemplateBasedVM. 5. Reboot the TemplateBasedVM.
6. Done. 6. Done.
If you added for example folder `/var/lib/tor` to the `binds` variable, from now on any files within that folder will persist reboots. If you added for example file `/etc/tor/torrc` to the `binds` variable, from now on any modifications to that file will persist reboots. From now on any files within the/var/lib/tor folder will persist across reboots.
You can make make many files or folders persist, simply by making multiple entries in the p50_user.conf file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots.
binds+=( '/var/lib/tor' )
binds+=( '/etc/tor/torrc' )
## Other Configuration Folders ## ## Other Configuration Folders ##
@ -54,35 +60,31 @@ If you added for example folder `/var/lib/tor` to the `binds` variable, from now
## How does it work? ## ## 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. bind-dirs.sh is called at startup of a TemplateBasedVM, and configuration files in the above configuration folders 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. 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. Creation of the files 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.
Note that you must create the full folder structure under /rw/bind-dirs - e.g you would have to create /rw/bind-dirs/var/lib/tor
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 ## ## Limitations ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh. * Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.
* Re-running `sudo /usr/lib/qubes/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/bind-dirs.sh umount` does not work. * Re-running `sudo /usr/lib/qubes/init/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/init/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. * Running `sudo /usr/lib/qubes/init/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. * 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. 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. * 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.
You can add persistent rules to `/etc/hosts` file using script `/rw/config/rc.local` that is designed to override configuration in /etc, starting services and etc. For example, to make software inside some TemplateBasedVM resolving the domain `example.com` as `127.0.0.1` open `/rw/config/rc.local` inside this TemplateBasedVM and add: You can add persistent rules to /etc/hosts using [/rw/config/rc.local][config-file]
~~~
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
After every boot of the TemplateBasedVM `rc.local` script will add line `127.0.0.1 example.com` to `/etc/hosts` file and the software inside the TemplateBasedVM will resolve domain `example.com` accordingly. You cam add several rules to `/etc/hosts` the same way.
## 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. `binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are sourced 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. 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. 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, you could use the following in:
`/rw/config/qubes-bind-dirs.d/50_user.conf` `/rw/config/qubes-bind-dirs.d/50_user.conf`
@ -96,3 +98,5 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
[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) [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)
[config-file]: /doc/config-files
[whonix]: https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5

5
user/advanced-configuration/config-files.md
View File

@ -29,6 +29,11 @@ The scripts here all run as root.
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~ ~~~
~~~
# Add entry to /etc/hosts
echo '127.0.0.1 example.com >> /etc/hosts
~~~
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change. - `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update. - In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` after each firewall update.