#1487 closed enhancement (fixed)
remove the notion of "rootcap" from FTP-and-SFTP.rst
Reported by: | zooko | Owned by: | amiller |
---|---|---|---|
Priority: | normal | Milestone: | undecided |
Component: | documentation | Version: | 1.8.2 |
Keywords: | docs usability ftp reviewed | Cc: | |
Launchpad Bug: |
Description
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?"
Attachments (1)
Change History (14)
Changed at 2011-08-17T21:45:01Z by zooko
comment:1 Changed at 2011-08-17T21:48:45Z by zooko
comment:2 Changed at 2011-08-17T22:02:11Z by 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.
comment:3 Changed at 2011-08-17T22:51:30Z by 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.
comment:4 follow-up: ↓ 8 Changed at 2011-08-19T02:20:58Z by 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.
comment:5 Changed at 2012-03-29T19:46:20Z by davidsarah
- Component changed from unknown to documentation
- Keywords review-needed added
- Owner changed from nobody to davidsarah
- Priority changed from major to normal
- Status changed from new to assigned
comment:6 Changed at 2012-03-30T22:59:06Z by davidsarah
- Owner changed from davidsarah to amiller
- Status changed from assigned to new
comment:7 Changed at 2012-03-30T23:03:04Z by amiller
- Status changed from new to assigned
comment:8 in reply to: ↑ 4 Changed at 2012-03-30T23:25:32Z by 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.
comment:9 Changed at 2012-03-30T23:26:41Z by amiller
- Keywords reviewed added; review-needed removed
comment:10 Changed at 2012-03-31T02:33:29Z by david-sarah@…
- Resolution set to fixed
- Status changed from assigned to closed
In 1562e2a3021344ab:
comment:11 Changed at 2012-03-31T02:35:48Z by davidsarah
remove-rootcap-from-docs.darcs.patch was applied 8 months ago in 43ba172f65aaa038.
comment:12 Changed at 2012-03-31T02:56:30Z by 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.
comment:13 Changed at 2012-03-31T18:02:51Z by david-sarah <david-sarah@…>
In 1562e2a3021344ab:
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".