bind-dirs docs are wrong #2661

Rudd-O · Mar 3, 2017

at no point is it mentioned that the user is supposed to place the bound dir or file into /rw/bind-dirs/<full path to file to shadow in the original file system>

I wasted 15 minutes with trial and error because I did not know this.

Technically, you're right. But the idea of bind-dirs is that you configure what file/directory should persist, and then modify it in it's original place (after calling bind-dirs, or restarting a VM).

marmarek · Mar 3, 2017

Technically, you're right. But the idea of bind-dirs is that you configure what file/directory should persist, and then modify it in it's original place (after calling bind-dirs, or restarting a VM).

Do please document that, cos it's not mentioned either. All it says is "Done" as the last step. No indication that the user should edit a file or whatevs.

Also, some of us automate things upfront, we aren't in the business of editing files after a reboot, so for us, we need to know where the bound file will be stored.

A section "How does it work?" would also be useful.

Rudd-O · Mar 3, 2017

Do please document that, cos it's not mentioned either. All it says is "Done" as the last step. No indication that the user should edit a file or whatevs.

Also, some of us automate things upfront, we aren't in the business of editing files after a reboot, so for us, we need to know where the bound file will be stored.

A section "How does it work?" would also be useful.

@Rudd-O I don't understand the issue -

the user is supposed to place the bound dir or file into /rw/bind-dirs/

No they're not - creating the entry and rebooting should do this automatically. If it doesn't then it's a bug and should be reported as such. It's not a documentation issue.

Can you provide more detail on what you are doing? (I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.)
If you dont want to change the file what are you using bind-dirs for? If you simply want to change a file in the template you can already do this with the edited file in /rw/config and an appropriate entry in rc.local

A section "How does it work?" would also be useful

Yes it would.

unman · Mar 3, 2017

@Rudd-O I don't understand the issue -

the user is supposed to place the bound dir or file into /rw/bind-dirs/

No they're not - creating the entry and rebooting should do this automatically. If it doesn't then it's a bug and should be reported as such. It's not a documentation issue.

Can you provide more detail on what you are doing? (I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.)
If you dont want to change the file what are you using bind-dirs for? If you simply want to change a file in the template you can already do this with the edited file in /rw/config and an appropriate entry in rc.local

A section "How does it work?" would also be useful

Yes it would.

Improved usage instructions a bit:
QubesOS/qubes-doc#296

adrelanos · Mar 3, 2017

Improved usage instructions a bit:
QubesOS/qubes-doc#296

unman:

(I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.)

What's the workaround?

adrelanos · Mar 3, 2017

unman:

(I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.)

What's the workaround?

Step 1: Create conf file. Step 2: Where do I place the replacement file? I already know what I want the file to be! It's not documented anywhere. So I assumed foolishly it went into /rw/config/bind-dirs.d (it doesn't, but I shouldn't have to read the code to find that out). Step 3: reboot. After this, it should just work properly, but because there are no docs saying "place your file here before rebooting" (a perfectly legal thing to do, especially when the whole setup is automated, as it is in my case), I wasted time on a wrong assumption.

…

On March 3, 2017 1:34:18 PM GMT+01:00, unman ***@***.***> wrote: @Rudd-O I don't understand the issue - > the user is supposed to place the bound dir or file into /rw/bind-dirs/ No they're not - creating the entry and rebooting *should* do this automatically. If it doesn't then it's a bug and should be reported as such. It's not a documentation issue. Can you provide more detail on what you are doing? (I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.) If you dont want to change the file what are you using bind-dirs for? If you simply want to change a file in the template you can already do this with the edited file in /rw/config and an appropriate entry in rc.local > A section "How does it work?" would also be useful Yes it would. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Rudd-O · Mar 3, 2017

Step 1: Create conf file. Step 2: Where do I place the replacement file? I already know what I want the file to be! It's not documented anywhere. So I assumed foolishly it went into /rw/config/bind-dirs.d (it doesn't, but I shouldn't have to read the code to find that out). Step 3: reboot. After this, it should just work properly, but because there are no docs saying "place your file here before rebooting" (a perfectly legal thing to do, especially when the whole setup is automated, as it is in my case), I wasted time on a wrong assumption.

…

On March 3, 2017 1:34:18 PM GMT+01:00, unman ***@***.***> wrote: @Rudd-O I don't understand the issue - > the user is supposed to place the bound dir or file into /rw/bind-dirs/ No they're not - creating the entry and rebooting *should* do this automatically. If it doesn't then it's a bug and should be reported as such. It's not a documentation issue. Can you provide more detail on what you are doing? (I wonder if you are trying to persist a file that is in the TemplatebasedVM but doesn't yet exist in the root.img - that's explicitly ruled out in the documentation, although there is a workaround.) If you dont want to change the file what are you using bind-dirs for? If you simply want to change a file in the template you can already do this with the edited file in /rw/config and an appropriate entry in rc.local > A section "How does it work?" would also be useful Yes it would. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Your pull request is wrong. You use bind dirt in the appvm. It also changes good docs into command line examples. Please don't merge that. I will come up with something that explains the situation better when I get home tomorrow.

…

On March 3, 2017 5:21:44 PM GMT+01:00, Patrick Schleizer ***@***.***> wrote: Improved usage instructions a bit: QubesOS/qubes-doc#296 -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Rudd-O · Mar 3, 2017

Your pull request is wrong. You use bind dirt in the appvm. It also changes good docs into command line examples. Please don't merge that. I will come up with something that explains the situation better when I get home tomorrow.

…

On March 3, 2017 5:21:44 PM GMT+01:00, Patrick Schleizer ***@***.***> wrote: Improved usage instructions a bit: QubesOS/qubes-doc#296 -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

@adrelanos

What's the workaround?

Put the files in /rw/bind-dirs...
Edit bind-dirs.sh in template to create the ro file/directory if it doesn't already exist. I wouldn't want to see this in the released code.

@Rudd-O I think I understand your issue.
I'll try something and see if it matches your expectations,(which are a use case that @adrelanos hadn't considered.)

unman · Mar 3, 2017

@adrelanos

What's the workaround?

Put the files in /rw/bind-dirs...
Edit bind-dirs.sh in template to create the ro file/directory if it doesn't already exist. I wouldn't want to see this in the released code.

@Rudd-O I think I understand your issue.
I'll try something and see if it matches your expectations,(which are a use case that @adrelanos hadn't considered.)

Rudd-O:

Your pull request is wrong. You use bind dirt in the appvm.

Which is exactly as bind-dirs.sh is supposed to be used. bind-dirs is mainly supposed to be used inside TemplateBasedVM really. Originally it was called bind-directories, was Qubes-Whonix specific, had no config and whatnot, written by nrgaway. I then generalized the whole thing and upstreamed it to Qubes. I wrote the original documentation. It's all in the git history. One of the main purpose of bind-dirs is in sys-whonix making /var/lib/tor (persistent Tor entry guards Tor security feature) as well as /etc/tor/torrc persistent. Due to my authorship, I feel confident to say, that my pull request is correct. I am glad if bind-dirs is useful for other setups. That's why I upstreamed it. However, please don't break it for the Qubes-Whonix use case. Having said this, you are most welcome to fix any limitations of bind-dirs at the code and/or documentation level.

adrelanos · Mar 3, 2017

Rudd-O:

Your pull request is wrong. You use bind dirt in the appvm.

Which is exactly as bind-dirs.sh is supposed to be used. bind-dirs is mainly supposed to be used inside TemplateBasedVM really. Originally it was called bind-directories, was Qubes-Whonix specific, had no config and whatnot, written by nrgaway. I then generalized the whole thing and upstreamed it to Qubes. I wrote the original documentation. It's all in the git history. One of the main purpose of bind-dirs is in sys-whonix making /var/lib/tor (persistent Tor entry guards Tor security feature) as well as /etc/tor/torrc persistent. Due to my authorship, I feel confident to say, that my pull request is correct. I am glad if bind-dirs is useful for other setups. That's why I upstreamed it. However, please don't break it for the Qubes-Whonix use case. Having said this, you are most welcome to fix any limitations of bind-dirs at the code and/or documentation level.

On March 3, 2017 7:59:41 PM GMT+01:00, unman ***@***.***> wrote: @adrelanos > What's the workaround? Put the files in /rw/bind-dirs... Edit bind-dirs.sh in template to create the ro file/directory if it doesn't already exist. I wouldn't want to see this in the released code. @Rudd-O I *think* I understand your issue. I'll try something and see if it matches your expectations,(which are a use case that @adrelanos hadn't considered.)

Thanks. Automation of dozens of VMs is a use case we ought to consider. Manually editing files after a reboot is too time consuming to consider as a solution unless it's a one off kind of thing. -- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Rudd-O · Mar 3, 2017

On March 3, 2017 7:59:41 PM GMT+01:00, unman ***@***.***> wrote: @adrelanos > What's the workaround? Put the files in /rw/bind-dirs... Edit bind-dirs.sh in template to create the ro file/directory if it doesn't already exist. I wouldn't want to see this in the released code. @Rudd-O I *think* I understand your issue. I'll try something and see if it matches your expectations,(which are a use case that @adrelanos hadn't considered.)

Thanks. Automation of dozens of VMs is a use case we ought to consider. Manually editing files after a reboot is too time consuming to consider as a solution unless it's a one off kind of thing. -- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Nothing will be broken in the process of improving the docs. Don't worry. It'll be fine. :-)

…

On March 3, 2017 8:17:32 PM GMT+01:00, Patrick Schleizer ***@***.***> wrote: Rudd-O: > Your pull request is wrong. You use bind dirt in the appvm. Which is exactly as bind-dirs.sh is supposed to be used. bind-dirs is mainly supposed to be used inside TemplateBasedVM really. Originally it was called bind-directories, was Qubes-Whonix specific, had no config and whatnot, written by nrgaway. I then generalized the whole thing and upstreamed it to Qubes. I wrote the original documentation. It's all in the git history. One of the main purpose of bind-dirs is in sys-whonix making /var/lib/tor (persistent Tor entry guards Tor security feature) as well as /etc/tor/torrc persistent. Due to my authorship, I feel confident to say, that my pull request is correct. I am glad if bind-dirs is useful for other setups. That's why I upstreamed it. However, please don't break it for the Qubes-Whonix use case. Having said this, you are most welcome to fix any limitations of bind-dirs at the code and/or documentation level. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Rudd-O · Mar 4, 2017

Nothing will be broken in the process of improving the docs. Don't worry. It'll be fine. :-)

…

On March 3, 2017 8:17:32 PM GMT+01:00, Patrick Schleizer ***@***.***> wrote: Rudd-O: > Your pull request is wrong. You use bind dirt in the appvm. Which is exactly as bind-dirs.sh is supposed to be used. bind-dirs is mainly supposed to be used inside TemplateBasedVM really. Originally it was called bind-directories, was Qubes-Whonix specific, had no config and whatnot, written by nrgaway. I then generalized the whole thing and upstreamed it to Qubes. I wrote the original documentation. It's all in the git history. One of the main purpose of bind-dirs is in sys-whonix making /var/lib/tor (persistent Tor entry guards Tor security feature) as well as /etc/tor/torrc persistent. Due to my authorship, I feel confident to say, that my pull request is correct. I am glad if bind-dirs is useful for other setups. That's why I upstreamed it. However, please don't break it for the Qubes-Whonix use case. Having said this, you are most welcome to fix any limitations of bind-dirs at the code and/or documentation level. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #2661 (comment)

-- Sent from my Android device with K-9 Mail. Please excuse my brevity.

Is all this really needs just a note saying that the dirs which are actually bind-mounted (containing the persistent data) reside in /rw/bind-dirs?

Edit: nevermind, just saw the comments here

jpouellet · Mar 15, 2017

Is all this really needs just a note saying that the dirs which are actually bind-mounted (containing the persistent data) reside in /rw/bind-dirs?

Edit: nevermind, just saw the comments here

On 03/15/2017 05:41 AM, Jean-Philippe Ouellet wrote: Is all this really needs just a note saying that the dirs which are actually bind-mounted (containing the persistent data) reside in |/rw/bind-dirs|? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2661 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAVIwr9wtzZkEliW9iacjezeoG2SWJRmks5rl3n3gaJpZM4MSElW>.

That would be a great start. An explanation of the mechanism and when it kicks in would also be great.

…

-- Rudd-O http://rudd-o.com/

Rudd-O · Mar 15, 2017

On 03/15/2017 05:41 AM, Jean-Philippe Ouellet wrote: Is all this really needs just a note saying that the dirs which are actually bind-mounted (containing the persistent data) reside in |/rw/bind-dirs|? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2661 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAVIwr9wtzZkEliW9iacjezeoG2SWJRmks5rl3n3gaJpZM4MSElW>.

That would be a great start. An explanation of the mechanism and when it kicks in would also be great.

…

-- Rudd-O http://rudd-o.com/

marmarek added the C: doc label Mar 3, 2017

andrewdavidwong added this to the Documentation/website milestone Mar 3, 2017

andrewdavidwong added help wanted task labels Mar 3, 2017

adrelanos added a commit to adrelanos/qubes-doc that referenced this issue Mar 3, 2017

clarify bind-dirs usage
https://www.qubes-os.org/doc/bind-dirs/ QubesOS/qubes-issues#2661

eca1423

adrelanos referenced this issue in QubesOS/qubes-doc Mar 3, 2017
Merged
clarify bind-dirs usage #296

unman referenced this issue in QubesOS/qubes-doc Mar 3, 2017
Merged
Clarify some issues regarding bind-dirs #299

adrelanos referenced this issue Mar 5, 2017
Open
make bind-dirs idempotent / allow re-running bind-dirs #2673

ypid referenced this issue in QubesOS/qubes-core-agent-linux Mar 16, 2017
Merged
bind-dirs: Create ro if bind target exists #42

qubesos-bot referenced this issue in QubesOS/updates-status Apr 1, 2017
Closed
core-agent-linux v3.2.17 (r3.2) #21

andrewdavidwong changed the title from binddirs docs are wrong to bind-dirs docs are wrong Oct 31, 2017

QubesOS/qubes-issues

Join GitHub today

bind-dirs docs are wrong #2661

Comments

Rudd-O commented Mar 3, 2017 • edited Edited 1 time Rudd-O edited Mar 3, 2017 (most recent)

This comment has been minimized.

marmarek commented Mar 3, 2017

marmarek added the C: doc label Mar 3, 2017

This comment has been minimized.

Rudd-O commented Mar 3, 2017 • edited Edited 1 time Rudd-O edited Mar 3, 2017 (most recent)

andrewdavidwong added this to the Documentation/website milestone Mar 3, 2017

andrewdavidwong added help wanted task labels Mar 3, 2017

This comment has been minimized.

unman commented Mar 3, 2017

adrelanos added a commit to adrelanos/qubes-doc that referenced this issue Mar 3, 2017

adrelanos referenced this issue in QubesOS/qubes-doc Mar 3, 2017

This comment has been minimized.

adrelanos commented Mar 3, 2017

This comment has been minimized.

adrelanos commented Mar 3, 2017

This comment has been minimized.

Rudd-O commented Mar 3, 2017

This comment has been minimized.

Rudd-O commented Mar 3, 2017

This comment has been minimized.

unman commented Mar 3, 2017

This comment has been minimized.

adrelanos commented Mar 3, 2017

This comment has been minimized.

Rudd-O commented Mar 3, 2017

unman referenced this issue in QubesOS/qubes-doc Mar 3, 2017

This comment has been minimized.

Rudd-O commented Mar 4, 2017

adrelanos referenced this issue Mar 5, 2017

This comment has been minimized.

jpouellet commented Mar 15, 2017 • edited Edited 1 time jpouellet edited Mar 15, 2017 (most recent)

This comment has been minimized.

Rudd-O commented Mar 15, 2017

ypid added a commit to ypid/qubes-core-agent-linux that referenced this issue Mar 16, 2017

ypid added a commit to ypid/qubes-core-agent-linux that referenced this issue Mar 16, 2017

ypid added a commit to ypid/qubes-core-agent-linux that referenced this issue Mar 16, 2017

ypid added a commit to ypid/qubes-core-agent-linux that referenced this issue Mar 16, 2017

ypid referenced this issue in QubesOS/qubes-core-agent-linux Mar 16, 2017

qubesos-bot referenced this issue in QubesOS/updates-status Apr 1, 2017

andrewdavidwong changed the title from binddirs docs are wrong to bind-dirs docs are wrong Oct 31, 2017

Rudd-O commented Mar 3, 2017 •

edited

Edited 1 time

Rudd-O edited Mar 3, 2017 (most recent)

Rudd-O commented Mar 3, 2017 •

edited

Edited 1 time

Rudd-O edited Mar 3, 2017 (most recent)

jpouellet commented Mar 15, 2017 •

edited

Edited 1 time

jpouellet edited Mar 15, 2017 (most recent)