The documentation TODO contains an item on the bsnmpd daemon. This fix contains a change to the handbook to add a section to the network-daemons chapter. Please comment on its suitability.
Fix: Apply the following patch to the handbook.
Patch attached with submission follows:
How-To-Repeat: Look up the handbook.
On Mon, 4 Apr 2011, Mark Meyer wrote:
> ? bsnmpd.diff
> Index: network-servers/chapter.sgml
> RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml,v
> retrieving revision 1.129
> diff -u -r1.129 chapter.sgml
> --- network-servers/chapter.sgml 4 Apr 2011 05:23:33 -0000 1.129
> +++ network-servers/chapter.sgml 4 Apr 2011 21:40:56 -0000
> @@ -5383,6 +5383,125 @@
> by local users.</para>
> + <sect1 id="network-bsnmpd">
> + <sect1info>
> + <authorgroup>
> + <author>
> + <firstname>Mark</firstname>
> + <surname>Meyer</surname>
> + <contrib>Contributed by </contrib>
> + </author>
> + </authorgroup>
> + <authorgroup>
> + <author>
> + <contrib>Updated by </contrib>
> + <othername>The &os; Documentation Project</othername>
> + </author>
> + </authorgroup>
> + </sect1info>
> + <title>The <application>bsnmpd</application> Server</title>
> + <sect2 id="network-bsnmpd-overview">
> + <title>Overview</title>
> + <para>With your first installation of FreeBSD, bsnmpd is
It's not clear that the ordinality of the installation is relevant.
> + provided as the default software implementing SNMPv2. For the
> + purpose of testing we will assume you're trying to connect to
> + this service from your local system.</para>
> + <note><para>NTo run the tests in this section you will additionally
> + need <filename role="package">net-mgmt/bsnmptools</filename>,
> + which you can install via the bsnmptools package or
> + port.</para></note>
> + </sect2>
> + <sect2 id="network-bsnmpd-configuring">
> + <title>Configuring <application>bsnmpd</application></title>
> + <para>The bsnmpd configuration resides in /etc/bsnmpd.config and
> + is already in a runnable state. By default bsnmpd allows
I think "the default configuration is runnable" is more clear.
> + anybody to read any variable using the community "public". If
> + you don't want everybody to read your SNMP variables, choose a
> + different read community and edit the configuration setting
> + accordingly:</para>
> + <programlisting>read := "superprivate"</programlisting>
> + <note><para>Choose the community string wisely. Everybody able to
I have a general preference for "everyone" over "everybody" that I cannot
really justify to this audience and will refrain from noting all
occurrences. However, here I think "anyone" or "everyone" is preferable.
> + guess it, will be able to read from your systems management
> + 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.
> + <para>The variables "location" and "contact" can be set. They
> + are intended to reflect the physical location and system
> + administration contact respectively:</para>
> + <programlisting>location := "Room 200"
> +contact := "email@example.com"</programlisting>
> + <para>If you want to send SNMP traps to a specific port, set
> + both "traphost" and "trapport" variables:</para>
> + <programlisting>traphost := monitor.example.com
> +trapport := 162</programlisting>
> + </sect2>
> + <sect2 id="network-bsnmpd-running">
> + <title>Running <application>bsnmpd</application></title>
> + <para>To run bsnmpd at system startup, add the following to your
> + <filename>/etc/rc.conf</filename>:</para>
> + <programlisting>bsnmpd_enabl="YES"</programlisting>
> + <para>Doing a</para>
Can you reword to avoid the awkwardness of treating the screenshot as part
of the sentence?
> + <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.
> + <screen>&prompt.root; <userinput>/usr/local/bin/bsnmpget -s superprivate@localhost sysContact</userinput>
> +sysContact.0 = firstname.lastname@example.org</screen>
> + <para>The command should dump the value you entered in your
s/dump/print/, I think (having not tried running the command)
> + configuration.</para>
Maybe name bsnmpd.config explicitly?
On Wed, 6 Apr 2011, Mark Meyer wrote:
> Thanks for your comments. I attached a revised patch. See below.
> 2011/4/6 Benjamin Kaduk <email@example.com>
>> + 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
> 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
>>> + <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
> Other changes: some markup, removed the word "now" preceding instructions
The capitalization of "RAM" is also inconsistent (it appears as "ram" at
-----BEGIN PGP SIGNED MESSAGE-----
this looks like a good addition to our handbook.
Can you work on a new patch that includes the latest feedback form Ben
Kaduk? I would be willing to help bring this into the handbook.
FreeBSD Doc Committer
The FreeBSD Documentation Project
FreeBSD German Documentation Project - https://doc.bsdgroup.de
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (Darwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
-----END PGP SIGNATURE-----
Set to feedback state until we get a response from the submitter
about the latest suggestions in the audit trail.
For bugs matching the following criteria:
Status: In Progress Changed: (is less than) 2014-06-01
Reset to default assignee and clear in-progress tags.
Mail being skipped
No update since 2011, so I'm closing it due to feedback timeout.