[OpenAFS-Doc] Forwarded documentation rant

[Jason Edgecombe]

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?

Sincerely,
Jason

-------- Original Message --------(edited to remove some information)
Jason,

After sending you my long tome, I just today had a look at
docs.openafs.org.  It's looking much better than when I looked a
couple of years ago.  Someone's done a lot of work.


-------- Original Message --------(edited to remove some information)

Jason,

As a perpetual OpenAFS newbie, it's always bothered me how well hidden
the basic documentation is from those who don't know where to look.
If you could add to your boilerplate a beginners link, that would be a
good thing.

Then of course, you need to build a worthy object of that link.  I see
you and Russ have a "better documentation" project.  The documents
tend to rapidly dive into details without much context.  Does such a
thing exist as a Concept of Operations ("conops") document for
OpenAFS?  I don't even know where to find the man pages on
openafs.org, short of downloading a source image and pulling the man
directory.  The conops document would provide the context so a reader
would know which man page to read when.  Although a large proportion
of your audience is programmers who take a lot of common software
engineering knowledge for granted, some of us are junior sysadmins who
get thrown, ready or not, into AFS.

An outline somewhere of skills needed for various roles in the care
and feeding of a cell would be useful.  One of the big disappointments
to the AFS community about Milicchio's book was that it focused on
basic skills, rather than documenting the esoterica.  Alas, what
basics he did document for us beginners were rapidly obsolete because
he made such a tight cookbook that as versions progress, all the
details change.  His book would have been much stronger as an outline
of skills, concepts and pointers for where to find the current
particulars.

I imagine a document, which starts after the sales pitch, with some of
the fundamental concepts of setting up a cell, something like:  To
start up a cell, you need a network which conveys UDP ports
7000-7003(?), a working time server and time synchronization scheme.
You probably also want some sort of DNS.  You need a candidate AFS
server, your first of several, running some form of Unix, with [a list
of particular packages].  If you happen to be running a Debian derived
Linux (Ubuntu, et. al.), you can get the right AFS stuff at..., and
public face of those packages is often Russ Allbery.  For Redhat
family distributions (RHEL, Centos,...), the AFS packaging can be
found at... Other popular operating systems for AFS servers include
Solaris, AIX, ...  Note that the AFS servers running on one operating
system are entirely compatible with AFS clients and other servers
running on other operating systems.

OpenAFS, the currently supported version of AFS, 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.  There are differences in interface and methodology,
but they are technically mostly interchangeable.  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.

Whether you use a pre-compiled version of OpenAFS or compile your own
is likely a decision based on your skills, comfort level and time
available.  Be warned that without some software diagnostic skills,
setting up and maintaining a cell can be an overwhelming challenge.
Here is a list of tools most of the developers will want you to
understand how to use when you need their help to fix a problem...  A
brief list is included in the release notes, but you would do well to
start with Wikipedia pages for these debugging and analysis tools and
then become a bit familiar with their use.

In the general daily experience of users of an established AFS system,
they see a large multi-organization shared file system represented as
/afs.  Below that level, are organizations, and below those depends on
the needs of each organization.  To have privileges in the system
beyond reading completely public documents, one must get an AFS token
via Kerberos.  In an organization which has set up a single sign-on
system, the user picks up the token (ticket) in the process of initial
login.  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.  A
cell is an administrative zone within AFS, sometimes representing a
large organization and sometimes a group within an organization.  Cell
names often mirror names in domain name service.  Note that Kerberos
and AFS talk about tickets and tokens, a similar concept, each
representing an identity within that system.  Kerberos tickets are
used to acquire AFS tokens, by which AFS knows which user is which and
what privileges have been assigned that user.  Privileges can vary by
directory, and can include the abilities to read files, write (change)
files, delete files, administer directory permissions...

I could go on, but I hope you get my drift.  I've hoped for a really
high level introduction to administering AFS, mostly so I can see what
skills I need to go out and learn; I don't know enough to write and
contribute it myself.  I use your newsletter and the mailing list to
educate myself, in a scattershot way, and to gauge whether OpenAFS is
a mature enough product to make sense for a person of limited software
engineering maturity, trying to get through life with a liberal arts
degree in computer science and no programming experience.  I've gotten
a lot from the mailing list by osmosis, but I still think the level of
my questions would annoy most people on the mailing lists, no matter
how genuine my efforts.  I am overwhelmed with all the stuff I'm aware
I don't know.  I'd at least appreciate guidance on what, where and how
to learn the skills to truly join the community, beyond the role of
village idiot.

My day job role is ***********,
trying to constantly justify the work of a bunch of bright software
engineers and to triage misunderstandings among managers.  I have yet
to be able to demonstrate to them why we would benefit as a group by
adopting AFS for our own operations, never mind that I'm somehow
supposed to efficiently share files with them across the country, as
well as have the ability to share files in a secure way with our
customer.  Most of my personal daily production is in spreadsheets,
emails and meetings, interrupted by an occasional phone call if really
necessary.  In my dreams, I'm a competent system administrator, with
lots of practice systems lying around the house.  My other interest at
the moment is learning virtualization systems, so I can clean house of
all those dinosaurs.  Progress is exceedingly slow.



On Tue, Apr 13, 2010 at 9:14 PM, Jason Edgecombe
<jason@rampaginggeek.com> wrote:
> If you could change anything about the newsletter, what would you change?