On 1/11/2012 5:32 AM, 夜神 岩男 wrote: > 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. I agree that's always a tricky question, but I think the problem here was that even if you knew a lot about Linux but just happened to be unfamiliar with SELinux, the documentation was still incorrect in ways that the reader wouldn't be able to figure out on their own. When the doc says "Access is only allowed between similar types", you can't make head or tail of that unless you already know what it means. >> 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... Yes, for software. But I've never heard of it being done for documentation. I suspect this is for two reasons: (1) if software fails, the dev does has to bite the bullet and make it work, but if documentation "fails", it's easy to blame the user (reader); (2) to get help testing your software, you can stay within the community of people who helped right it or those closely connected to them, but to get help testing documentation, you have to reach out to people far removed from your inner circle. (Plus, in theory you can only test the document on a single person one time. You can't use them to test future iterations of the same document, because then they might incorrectly report that the document is getting "clearer" when really their understanding is just becoming clearer from multiple readings and back-and-forth with the authors.) >> (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? I wasn't going to get into this, but... I did find the wiki contact page, and join their e-mail list, and post to the list asking to create an edit account so that I could make an edit (for starters, after the sentence about "you should re-label the file system", I was going to add a link to the steps on how to do that). I got one reply, replied to that, and the thread went dead. Here it is: http://lists.centos.org/pipermail/centos-docs/2012-January/thread.html Now, I understand if I kept bugging them, they might get back to me, and maybe my precious edit would actually happen. I think it's more of a mindset thing. Why not recruit some outsiders *before* the instructions ever even went live on the web, and say, "Here, read this, does it make sense to you?" > > 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... Well yes, sometimes you do end up learning more about a system, if you start out with wrong instructions, and you have to do a lot of asking and messing around to figure out why the instructions aren't working. But I think that's mainly because you have to spend far longer at it, than you would have spent, if the original instructions had worked. Given a *fixed* quantity of time to spend learning something, I think it would be far more productive to follow a set of instructions that guided you through actually doing several different things for practice (and which were correct instructions :) ), then banging away at one thing figuring out why it's wrong. Yes, I know that /tmp/ files don't get re-labeled properly, but that's pretty much the only thing I know. >> 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. Yes but at what cost? A lot of other things that I need to be working on, had to get put on hold because I have to figure out how to lock down the systems using SELinux, and spent four days working around one mistake in the documentation. (As I said, if someone's going to spend four days learning something, it's better to have self-guided lessons showing how to do multiple things -- but have the self-guided lessons proofread by outsiders :) ) > 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). Yes but I'm not sure if I made the right decision -- all that time lost was time I spent on other things. (Did anyone get the idea from the passwords/keys threads that I am a bit tenacious? :) ) But in the big picture it doesn't matter whether you think *I* made the right decision, if the vast majority of people are never going to invest that much time, and as a result, most people will just turn off SELinux instead. You can make one person's webserver more secure by encouraging them to read more, but you can only make the web as a whole more secure by making *defaults* better and making it a less arduous process to turn on things that are supposed to improve security. > 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! > _______________________________________________ > CentOS mailing list > CentOS at centos.org > http://lists.centos.org/mailman/listinfo/centos