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 gmail.com>
Cc: freebsd-gnats-submit at freebsd.org, freebsd-doc at freebsd.org
Subject: Re: docs/156187: Add bsnmpd to handbook
Date: Wed, 6 Apr 2011 01:19:36 -0400 (EDT)

 On Mon, 4 Apr 2011, Mark Meyer wrote:
 
 >
 > Patch attached with submission follows:
 >
 > ? 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 at 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 at localhost sysContact</userinput>
 > +sysContact.0 = sysmeister at 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