remove the notion of "rootcap" from FTP-and-SFTP.rst #1487

New Issue

zooko · 2011-08-17T21:44:44Z

zooko commented

2011-08-17 21:44:44 +00:00

Two different people have asked me for help, saying they couldn't figure out what a "rootcap" is. Hopefully just calling it a "cap" will make it easier for them to find out from the other docs what it is.

Brian objected on IRC, saying "we're removing information that non-beginner users would benefit from don't we have a glossary where "rootcap" could be defined in terms of caps and dircaps?"

Two different people have asked me for help, saying they couldn't figure out what a "rootcap" is. Hopefully just calling it a "cap" will make it easier for them to find out from the other docs what it is. Brian objected on IRC, saying "we're removing information that non-beginner users would benefit from don't we have a glossary where "rootcap" could be defined in terms of caps and dircaps?"

zooko added the

labels 2011-08-17 21:44:44 +00:00

zooko added this to the undecided milestone 2011-08-17 21:44:44 +00:00

zooko commented

2011-08-17 21:45:01 +00:00

Attachment remove-rootcap-from-docs.darcs.patch (37862 bytes) added

**Attachment** remove-rootcap-from-docs.darcs.patch (37862 bytes) added

remove-rootcap-from-docs.darcs.patch

37 KiB

zooko commented

2011-08-17 21:48:45 +00:00

I have the idea that Tahoe-LAFS is hard for people to understand, and maybe a reason for that is that it has too many concepts. The concept of a "rootcap" is, in my opinion, something that should be explained but not named. That is, we should tell people that a good way to keep track of their caps is to put them into a directory and then keep track of the cap to that directory, but we should not use the word "rootcap".

I have the idea that Tahoe-LAFS is hard for people to understand, and maybe a reason for that is that it has *too many concepts*. The concept of a "rootcap" is, in my opinion, something that should be explained but not named. That is, we should tell people that a good way to keep track of their caps is to put them into a directory and then keep track of the cap to that directory, but we should not use the word "rootcap".

zooko commented

2011-08-17 22:02:11 +00:00

Perhaps there are other contexts where the notion of a rootcap is more salient, but in source:docs/frontends/FTP-and-SFTP.rst, I'm not sure if it adds anything over "dir cap". The two users that I spoke to both were setting up FTP (or SFTP), and both were stymied by thinking that they couldn't use any old dir cap, they needed to get a special "root" cap, and didn't know where to get one or what was special about it. The thing is: there isn't anything special about it in the context of source:docs/frontends/FTP-and-SFTP.rst, is there? Any dir cap that you put in there is automatically what we call a "rootcap" isn't it? Or do I misunderstand the meaning of "rootcap"?

Or is the idea is that you should have only a single root cap that you use for all of your Tahoe-LAFS access, such as in your web browser bookmarks you should have a single entry for the root to all your Tahoe-LAFS resources, and when configuring your SFTP server you ought to put in the same root cap for it as you have in your bookmarks? I don't agree with that idea.

Perhaps there are other contexts where the notion of a rootcap is more salient, but in source:docs/frontends/FTP-and-SFTP.rst, I'm not sure if it adds anything over "dir cap". The two users that I spoke to both were setting up FTP (or SFTP), and both were stymied by thinking that they couldn't use any old dir cap, they needed to get a special "root" cap, and didn't know where to get one or what was special about it. The thing is: there *isn't* anything special about it in the context of source:docs/frontends/FTP-and-SFTP.rst, is there? Any dir cap that you put in there is automatically what we call a "rootcap" isn't it? Or do I misunderstand the meaning of "rootcap"? Or is the idea is that you should have only a single root cap that you use for all of your Tahoe-LAFS access, such as in your web browser bookmarks you should have a single entry for the root to all your Tahoe-LAFS resources, and when configuring your SFTP server you ought to put in the same root cap for it as you have in your bookmarks? I don't agree with that idea.

gdt commented

2011-08-17 22:51:30 +00:00

Without thinking much, I basically disagree. A rootcap is a special cap in that there is an expectation that it will be stored other than in some tahoe directory. In particular, it's something that a user has to both back up and keep secure. In many senses, if you think of mounting a tahoe filesystem, it's really a combination of introducer and rootcap that identifies a directory tree.

All that said, I have not found the term confusing. But it may need to be explained better and more consistently.

Without thinking much, I basically disagree. A rootcap is a special cap in that there is an expectation that it will be stored other than in some tahoe directory. In particular, it's something that a user has to both back up and keep secure. In many senses, if you think of mounting a tahoe filesystem, it's really a combination of introducer and rootcap that identifies a directory tree. All that said, I have not found the term confusing. But it may need to be explained better and more consistently.

davidsarah commented

2011-08-19 02:20:58 +00:00

The cap that is used as the root for an FTP/SFTP user account doesn't have any requirement or expectation that it not be stored in a Tahoe directory. (It is stored in the ftp.accounts file, but could easily be stored in a directory as well.) It's just any old directory cap, used in a particular way.

As far as I understood, the reason why some of our docs use the term "rootcap" is a historical one: at one point we only supported a single root for each user's "vdrive". Now that a path can start with any URI or any of multiple aliases (in the CLI at least, and #1346 would also give an alternative to logging in with a username and password in FTP/SFTP), there's no need for that concept.

OTOH, I think "root directory cap" in the original text meant "cap to an FTP or SFTP root directory". So I think it would be clearer to say:

... and second to decide what directory cap should be used as the root directory
for a log-in by the authenticated user.

The cap that is used as the root for an FTP/SFTP user account doesn't have any requirement or expectation that it not be stored in a Tahoe directory. (It is stored in the ftp.accounts file, but could easily be stored in a directory as well.) It's just any old directory cap, used in a particular way. As far as I understood, the reason why some of our docs use the term "rootcap" is a historical one: at one point we only supported a single root for each user's "vdrive". Now that a path can start with any URI or any of multiple aliases (in the CLI at least, and #1346 would also give an alternative to logging in with a username and password in FTP/SFTP), there's no need for that concept. OTOH, I think "root directory cap" in the original text meant "cap to an FTP or SFTP root directory". So I think it would be clearer to say: ``` ... and second to decide what directory cap should be used as the root directory for a log-in by the authenticated user. ```

tahoe-lafs added

and removed

labels 2012-03-29 19:46:20 +00:00

amiller commented

2012-03-30 23:25:32 +00:00

Since "rootcap" is not an actual kind of cap, I agree it's better not to specifically use it. In the (S)FTP docs, "what directory cap should be granted" conveys the right meaning. I've done a trac search for "rootcap" to look for any other interesting usages and did not find anything.

The definition in the wiki is still useful for understanding historical docs that refer to rootcaps.

From: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/Capabilities

We then use the somewhat-vague term "rootcap" to refer to a cap (usually a directory write cap) that is not present inside any directory, so the only way to ever reach it is to remember it somewhere outside of a Tahoe-LAFS filesystem.

Since "rootcap" is not an actual kind of cap, I agree it's better not to specifically use it. In the (S)FTP docs, "what directory cap should be granted" conveys the right meaning. I've done a trac search for "rootcap" to look for any other interesting usages and did not find anything. The definition in the wiki is still useful for understanding historical docs that refer to rootcaps. From: <https://tahoe-lafs.org/trac/tahoe-lafs/wiki/Capabilities> > We then use the somewhat-vague term "rootcap" to refer to a cap (usually a directory write cap) that is not present inside any directory, so the only way to ever reach it is to remember it somewhere outside of a Tahoe-LAFS filesystem.

david-sarah@jacaranda.org commented

2012-03-31 02:33:29 +00:00

In changeset:1562e2a3021344ab:

FTP-and-SFTP.rst: there were two more instances of 'rootcap'. Also made the wording tweak from ticket:1487#comment:4 . fixes #1487

In changeset:1562e2a3021344ab: ``` FTP-and-SFTP.rst: there were two more instances of 'rootcap'. Also made the wording tweak from ticket:1487#comment:4 . fixes #1487 ```

tahoe-lafs added the

fixed

label 2012-03-31 02:33:29 +00:00

tahoe-lafs closed this issue

2012-03-31 02:33:29 +00:00

davidsarah commented

2012-03-31 02:35:48 +00:00

remove-rootcap-from-docs.darcs.patch was applied 8 months ago in changeset:43ba172f65aaa038.

[remove-rootcap-from-docs.darcs.patch](/tahoe-lafs/trac-2024-07-25/attachments/000078ac-a7e2-2a90-0323-99090dc81586) was applied 8 months ago in changeset:43ba172f65aaa038.

zooko commented

2012-03-31 02:56:30 +00:00

Dang -- too bad someone forgot to remove review-needed 8 months ago so amiller redundantly reviewed it. On the other hand, redundancy is a great technique for detecting problems. :-) I'm glad amiller thought about this issue and agreed with the way it was handled.

Dang -- too bad someone forgot to remove `review-needed` 8 months ago so amiller redundantly reviewed it. On the other hand, redundancy is a great technique for detecting problems. :-) I'm glad amiller thought about this issue and agreed with the way it was handled.

david-sarah <david-sarah@jacaranda.org> commented

2012-03-31 18:02:51 +00:00

In changeset:1562e2a3021344ab:

FTP-and-SFTP.rst: there were two more instances of 'rootcap'. Also made the wording tweak from ticket:1487#comment:4 . fixes #1487

In changeset:1562e2a3021344ab: ``` FTP-and-SFTP.rst: there were two more instances of 'rootcap'. Also made the wording tweak from ticket:1487#comment:4 . fixes #1487 ```

Sign in to join this conversation.