docs/156187: Add bsnmpd to handbook

[Benjamin Kaduk]

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

From: Benjamin Kaduk <kaduk at MIT.EDU>
To: Mark Meyer <ofosos at googlemail.com>
Cc: freebsd-gnats-submit at 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 <kaduk at mit.edu>
 >
 >>  +       data.  The community will however be transferred in plain text
 >>>
 >>> +       over the wire, thus potentially leaking an otherwise secure
 >>> +       password to an attacker.</para></note>
 >>>
 >>
 >> "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 <screen> in a
 > full stop or in a colon?
 
 I personally prefer the colon, and there are examples in the Handbook to 
 support its use.
 
 >
 > +      <screen>&prompt.root; <userinput>/etc/rc.d/bsnmpd
 >>> start</userinput></screen>
 >>> +
 >>> +      <para>will start <application>bsnmpd</application>
 >>> +       immediately. To test your setup, run
 >>> +       an <application>bsnmpget</application> from the machine you
 >>> +       installed on.</para>
 >>>
 >>
 >> "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