From owner-freebsd-doc@FreeBSD.ORG Sun Nov 12 14:50:38 2006 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6D92A16A64B for ; Sun, 12 Nov 2006 14:50:38 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id D8E2643D8B for ; Sun, 12 Nov 2006 14:50:29 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.4/8.13.4) with ESMTP id kACEoTNN069323 for ; Sun, 12 Nov 2006 14:50:29 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.4/8.13.4/Submit) id kACEoTa6069322; Sun, 12 Nov 2006 14:50:29 GMT (envelope-from gnats) Date: Sun, 12 Nov 2006 14:50:29 GMT Message-Id: <200611121450.kACEoTa6069322@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Niclas Zeising Cc: Subject: Re: docs/104403: man security should mention that the usage of the X Window Systen is only possible with kern.securitylevel=-1 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Niclas Zeising List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 12 Nov 2006 14:50:38 -0000 The following reply was made to PR docs/104403; it has been noted by GNATS. From: Niclas Zeising To: Giorgos Keramidas Cc: bug-followup@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 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