Bug 156187 - [handbook] [patch] Add bsnmpd to handbook
Summary: [handbook] [patch] Add bsnmpd to handbook
Status: Closed Feedback Timeout
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc mailing list
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2011-04-04 23:00 UTC by Mark Meyer
Modified: 2019-06-08 10:30 UTC (History)
1 user (show)

See Also:


Attachments
file.txt (4.71 KB, text/plain)
2011-04-04 23:00 UTC, Mark Meyer
no flags Details
bsnmpd02.diff.txt (4.87 KB, text/plain; charset=US-ASCII)
2011-04-06 09:01 UTC, ofosos
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Mark Meyer 2011-04-04 23:00:22 UTC
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.
Comment 1 Ben Kaduk 2011-04-06 06:19:36 UTC
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>
>     </sect2>
>   </sect1>
> +
> +  <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

Spurious 'N'.

> +	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

no comma.

> +	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 := "sysmeister@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>

"enable"

> +
> +      <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 = sysmeister@example.com</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?


-Ben Kaduk
Comment 2 Ben Kaduk 2011-04-07 00:13:14 UTC
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
Comment 3 Benedict Reuschling freebsd_committer 2011-05-26 08:39:29 UTC
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Mark,

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.

Thanks!

Benedict Reuschling
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/

iEYEARECAAYFAk3eA6sACgkQTSZQLkqBk0hgTwCgizmK6EfISlH6Mn8qO+93ODBA
t5YAnRckZhQg4kp2OVBKBYCXUI6DjTSp
=2Ldx
-----END PGP SIGNATURE-----
Comment 4 Benedict Reuschling freebsd_committer 2011-06-21 13:59:13 UTC
State Changed
From-To: open->feedback

Set to feedback state until we get a response from the submitter 
about the latest suggestions in the audit trail.
Comment 5 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 08:01:15 UTC
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
Comment 6 Benedict Reuschling freebsd_committer 2019-06-08 10:30:38 UTC
No update since 2011, so I'm closing it due to feedback timeout.