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

[zooko]

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]

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]

Perhaps there are other contexts where the notion of a rootcap is more salient, but in 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 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]

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]

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.

[amiller]

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@…]

In 1562e2a3021344ab:

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

[davidsarah]

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

[zooko]

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@…>]

In 1562e2a3021344ab:

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