On 01/11/2012 07:19 PM, Bennett Haselton wrote: > Well there is already a beginner-friendly introduction: > http://wiki.centos.org/HowTos/SELinux > The problem I had with it is that there are several statements that are > unclear, missing, or just wrong. That's not necessarily the fault of the > author; if I had to write an intro to something that I knew a lot about, > I'd probably also make a few statements that were unclear or wrong. Tell me about it. I constantly find myself really great at writing docs for systems that the audience is already expert in, but somewhat lacking on writing it for complete beginners. Really, the principal problem is one of prereqs. Teaching people on this list about SELinux is a lot easier than teaching professional diesel mechanics about it, and a bit harder than teaching a certain breed of security researchers about it. So at what level is appropriate to begin the explanation? This is tricky. > The cure for that is to show it to 10 people whose intelligence you are > reasonably confident about, but who *don't already know* what the > document is trying to teach, and ask them to suggest edits: anything > that tells the user to "do something" without saying how, or is unclear, > or doesn't work when they try it. Then when the documentation has been > tweaked enough that it no longer has too many of those problem areas, > then it's "ready". This is sounds very much the way open source development works. And its the process you're engaging in, actually. See below... > (If I were a volunteer, some of my suggested edits to that page would be: > - Near the beginning the doc says "the machine should be rebooted and > the filesystem relabeled", without telling the user how to actually do > that. Have a forward-reference telling the user where to read how to > relabel the filesystem. > - The sentence about "Access is only allowed between similar types" is > apparently wrong (and meaningless anyway if it doesn't explain what > "similar types" means). I would just go ahead and say that there's no > way to know for sure what process types will be allowed to access what > file types, and all you can do is make educated guesses based on the > similarity of the names, and then look at error logs afterwards to see > if you were right. > - Explain that files in /tmp/ aren't relabeled after rebooting. (If > indeed that is the case. We never did figure out why my /tmp/ files > weren't being relabeled.) > - The "genhomedircon" command gives an error if SELinux is enforcing; > switch to permissive before running that command. > - The doc says httpd runs in the httpd_t security context. This is only > true if it's started silently; if the user starts it from the command > line, it runs in a different context.) And you should *really* cc this bit to the author. Anyway, you said it is a wiki -- so why don't you get to wikifying instead of writing on a mailinglist? That's the heart of the process! This is a system under development, and as such needs your help. How great would it be for you to document your trouble spots in learning and contribute that back? Most of the best tutorials on the web started that way -- as a "how to learn how to learn systemX based on my personal experience" type of document. A roadmap for learning is never more accurate than the one written by a learner himself. There is a secondary benefit to this -- it forces you as a learner to really understand your subject, which makes the learning more complete for you. Its a win-win, give it a spin! If nobody did that we wouldn't even have a kernel, by the way... > It doesn't take that much work to turn so-so documentation into really > useful documentation, but you have to start with the assumption that > there is room for improvement. The main obstacle is the attitude of > people like John Dennison, who assume the documentation is fine the way > it is, and that any problems are therefore the fault of the user: "If > people would bother to spend some time _reading_ _documentation_ on the > systems they are attempting to admin they might find that subsystems > such as selinux aren't quite as complex as they make them out to be... > Blaming selinux itself for creating what you perceive as a "problem" > because you won't make a rudimentary attempt at learning to properly > manage it is ludicrous." (Even though it subsequently came out that I > was in fact following the instructions on the wiki, and there were steps > missing in the instructions.) He's right in principle, if not in detail. You're right in principle, but you're also correct in the specific detail of practice as things stand right now. Every system we use is a moving target. JD was probably dead-on correct a few months ago. Things have changed, and the documentation likely doesn't take into account the specific version of the distro you're running, so some things could be missing. This happens a LOT, and its not really anyone's fault, per se -- that is entirely the wrong way of looking at it, especially in the open source world. > Why not try producing documentation that passes the 10-smart-newbies > test, and then point people to that, whenever they run into problems > caused by SELinux? > But if it takes an average of four days to fix a typical problem caused > by SELinux, *even following the documentation* (and even, for that > matter, having a whole list to help you!), then of course people aren't > going to use it. You went from nearly zero understanding to finding the solution in four days. In that span you didn't just "find the solution" as something that you cut and pasted from a forum without knowing what you were doing. You actually learned a bit about the system itself. This was what you initially lacked, but have now. The next time you have a problem and think its SELinux related you'll probably figure out how to troubleshoot it really fast, and then resolve it in a jiffy, and you'll sit there wondering "why did it take me four days before?!?" A lot of people coming from Windows spend well over a day just to make heads or tails of the Unix file permissions system, and longer than that when they have a real file permissions question that involves things like sticky group permissions on directories, for example. On the other hand millions of people literally spend hundreds of hours every month clicking mouse buttons at work on full salary to do things that a script could daily/hourly/whenever in less than a second -- but they don't take the time to learn how to do things like that because it (ironically) "seems like too much of a hassle". Hell, the entire concept of the web as an "applications development framework" is completely flawed but based on the premise that doing the required cheetahflips to make the web almost sorta-kinda secure is better than learning how real secure socket communications can work and taking the time to study just one or two languages and a single applications library deeply. The world is full of mistakes based on instant gratification, pretty pixels, chicken lipstick and fake tits that could have easily been prevented by prior planning and self-education. Blah blah blah. You did extremely well learning what you needed to and sticking with it (most people just give up, but instead you decided to learn -- which, over time, is how people accidentally get added to the development community, by the way). You could deepen that by documenting your experience even on just a personal blog or whatever and linking it from the wiki, or just letting Google catch it... others *will* be interested!