The OpenAFS documents contain 4 primary sections on upgrading existing AFS installs to the Gentoo openafs installs newer then 1.4. Later there is a single short section on actually Installing OpenAFS (Section 5), and only 1 section on setting up some basic pam support (and a very short section it is). It seems oddly confusing to have a generic OpenAFS document thats primary purpose is to give painfully detailed information about upgrading from an existing AFS install to a new one, and nearly no documentation on actually getting an OpenAFS system installed. As a secondary note, outside of section 6's mentioning of the pam configs for getting sudo working, no other services are mentioned. What about issues like token passing and single-sign-on functionality with OpenSSH and other packages? Or one of the more curious missing bits of information from the document, where are the instructions for an AFS/Kerberos Intigration path for existing AFS installs? The current documentation is painfully lacking and simply pointing people at OpenAFS.ORG's hand-me-down docs from Transarc is a sure way to not only confuse someone, but drive them away from AFS all together IMHO.
CCing stefaan, as he's the maintainer for this package. Stefaan, what do you think? Are these valid points, or do they make the guide needlessly complex/have nothing to do with it, or what? If you think these should go in in some order, a patch (however rough, diff -Nut) would be most appreciated. :)
I don't see the 4 primary sections on upgrading as mentioned in comment #0. Only section 2 is really about upgrading, the other primary sections are all generic. Section 4 is even about installing (not upgrading) the client. But just the fact that this isn't clear is probably enough of a reason to clarify/restructure parts of the documentation. I've only written the upgrade section of the documentation, and touched some other parts to correct obsolete pathnames etc. Unfortunately, upgrading can be a lot more difficult then a fresh install. However, this upgrade information roughly only applies to people crossing the 1.4.0-barrier. As most people probably already have upgraded, it may be useful to cut this part out, put it in its own page, and refer to it from within the current document. > What about issues like token passing and single-sign-on functionality with > OpenSSH and other packages? This has long been a very difficult issue, as the (unofficial) patches to get this working stopped doing so with the introduction of privilege separation into the OpenSSH code. As privilege separation has become more than just an option, but instead mandatory, this solution has ceased to exist. But as kerberos-4 has become old now, maybe this is not a big worry anymore. Maybe heimdal (or other kerberos-5) integration into OpenSSH solves this problem? Unfortunately, I'm not a kerberos-5 wizard, (actually still using kerberos 4 now, please don't shoot me) so input on this is appreciated. > Or one of the more curious missing bits of information from the document, > where are the instructions for an AFS/Kerberos Intigration path for existing > AFS installs? I think this even needs extra code that's not in portage yet (see bug #17465). If the reporter of this bug has some expertise on Kerberos 5, I would be happy to work with him to make both support and documentation better.
Any time you feel like contributing some additional documentation to this guide on the subjects you mentioned, feel free to reopen later. As it is, the guide maintainer seems to feel that it is sufficient to its purpose.
