docs/104403: man security should mention that the usage of the X Window Systen is only possible with kern.securitylevel=-1

[Niclas Zeising]

The following reply was made to PR docs/104403; it has been noted by GNATS.

From: Niclas Zeising <lothrandil at n00b.apagnu.se>
To: Giorgos Keramidas <keramida at FreeBSD.org>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/104403: man security should mention that the usage of the
 X Window Systen is only possible with kern.securitylevel=-1
Date: Sun, 12 Nov 2006 15:45:01 +0100

 Giorgos Keramidas wrote:
 > On 2006-11-12 14:55, Niclas Zeising <lothrandil at n00b.apagnu.se> wrote:
 >> Giorgos Keramidas wrote:
 >>> I'm not sure.
 >>>
 >>> Should we also mention that you can't "installworld" with an elevated
 >>> securelevel, because chflags may fail to work and cause problems?
 >>> Should we also mention that not being able to change the firewall
 >>> rules can be tricky, if you are testing your new firewall ruleset,
 >>> and get locked out?
 >>>
 >>> There are *MANY* ways in which an elevated securelevel can turn
 >>> around and bite you in the ass, but do we _really_ have to enumerate
 >>> them all in mind-boggingly detail?  ... in a single manpage?
 >>>
 >>> I really don't know.
 >> I believe they should be documented somewhere, to avoid questions.
 > 
 > I believe a manpage is not the right place for long, detailed, filled
 > with gory details explanation of all the possible scenarios that can go
 > wrong.  I mean, there are ways to destroy a system with rm(1) too, but
 > we don't have a list of funny, albeit dangerous "rm -fr /" scenarios in
 > that manpage too.
 
 I was not referring exclusively to a man page, rather that it should be 
 documented somewhere.  I agree with you that a man page is not the right 
 place for this type of documentation, it is more of a reference.  What 
 the man page can have is a reference to documentation which discuss 
 issues etc. in more detail so the user reading the man page knows where 
 to look if the information wasn't enough.
 
 > 
 > This sort of stuff, in my opinion, belongs to a tutorial style guide,
 > i.e.  something like a "Mini Guide for Security on FreeBSD".  A manpage
 > should be written as a 'reference' guide, but that's only *my* point of
 > view.
 
 Yup.
 
 > 
 >> But you are right in that there are numerous consequences in raising
 >> secure levels and that it might be a bit over the top to document them
 >> all.  Maybe I/we have to face the fact that it's too much and/or
 >> unnecessary to document all consequences, and rely on that if a
 >> sysadmin feels the need to raise the secure-level he knows what he's
 >> doing and the consequences of doing so.  Maybe the biggest issues in
 >> raising secure-level should be mentioned, but then again, who decides
 >> which those issues are?
 > 
 > EXACTLY!
 > 
 > Picking up what level of detail we want to appear in a manpage is not
 > easy if we let all the details about all potentially harmful scenarios
 > go in.  But if we treat manpages as 'reference' material, then the field
 > is much much more clear.
 
 True. Everybody just has to agree on that. I think it's a reasonable 
 line to draw: Man pages are references, tutorials and other documents 
 can go into more depth.  Maybe we should state that somewhere?  Or is 
 that to overdo things?
 
 > 
 > For example, we don't document all the different ways that fgets(3) can
 > be abused in its manpage.  We don't document all the potentially stupid
 > ways to use scanf(3) in its manpage either.  What we *do* write about in
 > most manpages is a `reference guide'.
 > 
 >> Maybe it's best to leave the documentation regarding this as it is,
 >> and give an answer whenever the issues pops up.
 > 
 > Or we can expand, extend and clean up the ``Security'' chapter of the
 > Handbook, which has the potential and the purpose of being a guide which
 > matches both a `tutorial' and `reference' styles (depending on how
 > complete and nicely written the relevant sections are, of course).
 
 I can see if I manage to hack some lines together regarding secure 
 level, since I'm already in the security chapter mucking about.
 I just hope I realize when I'm in for too much ;)
 Regards!
 //Niclas