Date: Wed, 6 Apr 2011 23:20:06 GMT From: Benjamin Kaduk <kaduk@MIT.EDU> To: freebsd-doc@FreeBSD.org Subject: Re: docs/156187: Add bsnmpd to handbook Message-ID: <201104062320.p36NK6Fu074778@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/156187; it has been noted by GNATS. From: Benjamin Kaduk <kaduk@MIT.EDU> To: Mark Meyer <ofosos@googlemail.com> 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 <kaduk@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201104062320.p36NK6Fu074778>