docs/156187: Add bsnmpd to handbook

[Mark Meyer]

>Number:         156187
>Category:       docs
>Synopsis:       Add bsnmpd to handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Mon Apr 04 22:00:22 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator:     Mark Meyer
>Release:        FreeBSD 8.2-RELEASE i386
>Organization:
n/a
>Environment:
System: FreeBSD nv-fbsd 8.2-RELEASE FreeBSD 8.2-RELEASE #0: Fri Feb 18 02:24:46
UTC 2011 root at almeida.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC i386
>Description:
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.
>How-To-Repeat:
Look up the handbook.
>Fix:
Apply the following patch to the handbook.

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
+        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
+	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
+	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>
+
+      <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>
+
+      <para>Doing a</para>
+
+      <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>
+
+      <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
+	configuration.</para>
+
+    </sect2>
+
+    <sect2 id="network-bsnmpd-module">
+      <title>Loading a module</title>
+
+      <para>Most of the bsnmpd functionality is available via
+	modules. For demonstration purposes we will load the host
+	resources module, which we will query for how much ram this
+	system has. In <filename>snmpd.config</filename> the mib-2 module is
+	already activated. We will add the host resources
+	module. Search for the following line and uncomment it, by
+	removing the hash sign in front:</para>
+
+      <programlisting>begemotSnmpdModulePath."hostres" = "/usr/lib/snmp_hostres.so"</programlisting>
+
+      <para>Now restart <application>bsnmpd</application>:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.d/bsnmpd restart</userinput></screen>
+
+      <para>Now you are able to query the amount of RAM (in kilobytes)
+	this system has:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/bin/bsnmpwalk -s superprivate at localhost -n 1.3.6.1.2.1.25.2.2</userinput>
+1.3.6.1.2.1.25.2.2 = 511392</screen>
+
+    </sect2>
+  </sect1>
+
 </chapter>
 
 <!--


>Release-Note:
>Audit-Trail:
>Unformatted: