From owner-freebsd-doc@FreeBSD.ORG Wed Apr 6 23:20:06 2011 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 8F0BB106566B for ; Wed, 6 Apr 2011 23:20:06 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 6FE008FC0A for ; Wed, 6 Apr 2011 23:20:06 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id p36NK6m6074779 for ; Wed, 6 Apr 2011 23:20:06 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id p36NK6Fu074778; Wed, 6 Apr 2011 23:20:06 GMT (envelope-from gnats) Date: Wed, 6 Apr 2011 23:20:06 GMT Message-Id: <201104062320.p36NK6Fu074778@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Benjamin Kaduk Cc: Subject: Re: docs/156187: Add bsnmpd to handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Benjamin Kaduk List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 06 Apr 2011 23:20:06 -0000 The following reply was made to PR docs/156187; it has been noted by GNATS. From: Benjamin Kaduk To: Mark Meyer Cc: freebsd-gnats-submit@freebsd.org Subject: Re: docs/156187: Add bsnmpd to handbook Date: Wed, 6 Apr 2011 19:13:14 -0400 (EDT) On Wed, 6 Apr 2011, Mark Meyer wrote: > Thanks for your comments. I attached a revised patch. See below. > > 2011/4/6 Benjamin Kaduk > >> + data. The community will however be transferred in plain text >>> >>> + over the wire, thus potentially leaking an otherwise secure >>> + password to an attacker. >>> >> >> "thus" is perhaps spurious; the whole sentence could probably be reworded >> to make it more clear that valuable passwords should not be used as they are >> sent in cleartext. > > > Now reads: " Choose the community string wisely. Everyone able to guess it > will be able to read from your systems management data. The community > string is transferred in cleartext over the network, potentially leaking a > valuable password to an attacker." I think the core thing that was tickling me was "potentially leaking" versus "potentially valuable". If there is an attacker who can sniff your network, he *will* read the password. The only question is whether the password is valuable. Now, this scenario is not universally applicable, so it is not really grounds for shaping the text. > > Express that the user doesn't want to use the very weak "public", or his/her > valuable user credentials. Do you have an opinion about starting the third > sentence with "But"? I do not think it is correct usage if the surrounding text is unchanged. To say "[b]ut provided that a unique value is used for the community string which is not a password elsewhere, the system management data is the only information leaked" would be correct usage, though rather tangential. > > Can you reword to avoid the awkwardness of treating the screenshot as part >> of the sentence? > > > "Start bsnmpd:" This feels a bit abrupt; I think "To start after system startup, use the command:" is closer to the prevailing style in existing text. > > Do you have a preference to end the sentence preceding the in a > full stop or in a colon? I personally prefer the colon, and there are examples in the Handbook to support its use. > > + &prompt.root; /etc/rc.d/bsnmpd >>> start >>> + >>> + will start bsnmpd >>> + immediately. To test your setup, run >>> + an bsnmpget from the machine you >>> + installed on. >>> >> >> "machine you installed on" is a somewhat awkward phrase. > > > I used "your system" elsewhere. The idea that you're doing this locally > should be evident. Sure. It would flow more smoothly here to say "on your machine", is my point. [...] > > Other changes: some markup, removed the word "now" preceding instructions > (superfluous). The capitalization of "RAM" is also inconsistent (it appears as "ram" at least once). -Ben Kaduk