[OpenAFS-Doc] Re: Forwarded documentation rant

[Andrew Deason]

On Sat, 17 Apr 2010 16:56:30 -0400
Jason Edgecombe wrote:

> Hi Everyone,
> 
> I wanted to share a user's rant about what is still needed in the 
> documentation. The first inclusion is a follow-up email. the second 
> inclusion is the original message.  Names and identifying info has
> been removed to protect the ranter. I'm working to help this person
> become a contributor. The rant has a lot of value for what is
> missing. Where else should these ideas be recorded?

The user guide, perhaps? I think a lot of this is covered there, but
maybe it's useful to have a single page with all of this overview
information? Maybe we just need to link to docs.openafs.org more often.

I think there are a lot of 'intro to [Open]AFS' guides out there, but
they're on random blogs or institution-specific sites. Until recently I
don't think we've had a good guide on openafs.org that can be updated
and kept correct. Does the quick start guide / the user guide cover
this?

There's also an old afs FAQ
<http://www.angelfire.com/hi/plutonic/afs-faq.html> that still gets
posted to usenet every month, despite it not being updated since 1998.
Perhaps that format could be used, but just updated and put somewhere
useful.

The provided text seems very good; but if we use it, a few nits
inline...

> [...]
> To start up a cell, you need a network which conveys UDP ports
> 7000-7003(?)

This isn't quite a simple thing to answer, since the ports you need open
depends on what functionality you want... but typically, I'd say you
want 7000, 7002, 7003, 7005 accessible on the servers, and 7001 on the
clients.

> OpenAFS, the currently supported version of AFS

'supported' by whom? It might be more meaningful to say "the most
popular implementation of AFS" or something about it being the only
implementation of AFS you can purchase support for (I think).

> depends on Kerberos, an authentication system developed at MIT.  You
> have a choice between the current version from MIT, krb5, or a
> compatible version from Sweden, Heimdal.

Both of these are Kerberos V / krb5. Note that you can also use Active
Directory, but I get the impression that's a bit less plug-and-play.

> Unless you happen to know a particular unique feature you want from
> one or the other, your decision will likely be guided by international
> politics and encryption export laws.

Encryption export laws aren't much of an issue these days, are they?

> Otherwise, the user must use the local tool(s) for authenticating to a
> Kerberos server, by which the user will gain credentials for the
> desired AFS cell, often klog followed by aklog.

Perhaps that is intended to be 'kinit followed by aklog'?

-- 
Andrew Deason
adeason@sinenomine.net