#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)

remove-rootcap-from-docs.darcs.patch (37.0 KB) - added by zooko at 2011-08-17T21:45:01Z.

Download all attachments as: .zip

Change History (14)

comment:1 Changed at 2011-08-17T21:48:45Z by 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".

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: 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:

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

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:

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

Note: See TracTickets for help on using tickets.