The R13B03 release.OTP_R13B03

1 files changed, 1030 insertions, 0 deletions

diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml
new file mode 100644
index 0000000000..073cdde308
--- /dev/null
+++ b/lib/snmp/doc/src/snmp_config.xml
@@ -0,0 +1,1030 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Running the application</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>snmp_config.xml</file>
+  </header>
+  <p>The chapter <em>Running the application</em> describes how the 
+    application is configured and started.
+    The topics include:</p>
+  <list type="bulleted">
+    <item>configuration directories and parameters</item>
+    <item>modifying the configuration files</item>
+    <item>starting the application (agent and/or manager)</item>
+    <item>debugging the application (agent and/or manager)</item>
+  </list>
+  <p>Refer also to the chapter(s) 
+    <seealso marker="snmp_agent_config_files">Definition of Agent  Configuration Files</seealso> and  
+    <seealso marker="snmp_manager_config_files">Definition of Manager  Configuration Files</seealso> which contains more detailed information 
+    about the agent and manager configuration files.</p>
+
+  <section>
+    <marker id="configuration_params"></marker>
+    <title>Configuring the application</title>
+    <p>The following two directories must exist in the system
+      to run the agent:</p>
+    <list type="bulleted">
+      <item>
+        <p>the <em>configuration directory</em> stores all
+          configuration files used by the agent (refer to the chapter 
+          <seealso marker="snmp_agent_config_files">Definition of Agent Configuration Files</seealso> for more information). </p>
+      </item>
+      <item>the <em>database directory</em> stores the internal
+       database files.</item>
+    </list>
+    <p>The following directory must exist in the system
+      to run the manager:</p>
+    <list type="bulleted">
+      <item>
+        <p>the <em>configuration directory</em> stores all
+          configuration files used by the manager (refer to the chapter 
+          <seealso marker="snmp_manager_config_files">Definition of Manager  Configuration Files</seealso> for more information). </p>
+      </item>
+      <item>
+         <p>the <em>database directory</em> stores the internal
+           database files. </p>
+      </item>
+    </list>
+
+    <p>The agent and manager uses (application) configuration parameters to 
+      find out where these directories are located. The parameters should be
+      defined in an Erlang system configuration file. The following
+      configuration parameters are defined for the SNMP application:</p>
+
+    <!-- Also in snmp_app.xml -->
+
+    <pre>
+      agent_options() = [agent_option()]
+      agent_option() = {restart_type,     restart_type()}     | 
+                       {agent_type,       agent_type()}       |  
+                       {agent_verbosity,  verbosity()}        |  
+                       {versions,         versions()}         |  
+                       {discovery,        agent_discovery()}  |  
+                       {priority,         priority()}         |  
+                       {multi_threaded,   multi_threaded()}   |  
+                       {db_dir,           db_dir()}           |  
+                       {db_init_error,    db_init_error()}    |  
+                       {local_db,         local_db()}         |  
+                       {net_if,           agent_net_if()}     |  
+                       {mibs,             mibs()}             |  
+                       {mib_storage,      mib_storage()}      |  
+                       {mib_server,       mib_server()}       |  
+                       {audit_trail_log,  audit_trail_log()}  |  
+                       {error_report_mod, error_report_mod()} |  
+                       {note_store,       note_store()}       |  
+                       {symbolic_store,   symbolic_store()}   |  
+                       {target_cache,     target_cache()}     |  
+                       {config,           agent_config()}
+      manager_options() = [manager_option()]
+      manager_option() = {restart_type,             restart_type()}    | 
+                         {net_if,                   manager_net_if()}  |  
+                         {server,                   server()}          | 
+                         {note_store,               note_store()}      | 
+                         {config,                   manager_config()}  |  
+                         {inform_request_behaviour, manager_irb()}     | 
+                         {mibs,                     manager_mibs()}    | 
+                         {priority,                 priority()}        |  
+                         {audit_trail_log,          audit_trail_log()} | 
+                         {versions,                 versions()}        | 
+                         {def_user_mod,             def_user_module()  | 
+                         {def_user_data,            def_user_data()}
+    </pre>
+
+    <p>Agent specific config options and types:</p>
+    <taglist>
+      <tag><c><![CDATA[agent_type() = master | sub <optional>]]></c></tag>
+      <item>
+        <p>If <c>master</c>, one master agent is
+          started. Otherwise, no agents are started. </p>
+        <p>Default is <c>master</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_discovery() = [agent_discovery_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>agent_discovery_opt() = 
+          {terminating, agent_terminating_discovery_opts()} | 
+          {originating, agent_originating_discovery_opts()}</c></p>
+        <p>The <c>terminating</c> options effects discovery initiated by 
+          a manager. </p>
+        <p>The <c>originating</c> options effects discovery initiated 
+          by this agent. </p>
+        <p>For defaults see the options in <c>agent_discovery_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_terminating_discovery_opts() = [agent_terminating_discovery_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>agent_terminating_discovery_opt() = 
+          {enable, boolean()} | 
+          {stage2, discovery | plain} | 
+          {trigger_username, string()}</c></p>
+        <p>These are options effecting discovery <c>terminating</c> in this
+          agent (i.e. initiated by a manager). </p>
+        <p>The default values for the <c>terminating</c> 
+          discovery options are: </p>
+        <list type="bulleted">
+          <item>enable: <c>true</c></item>
+          <item>stage2: <c>discovery</c></item>
+          <item>trigger_username: <c>""</c></item>
+        </list>
+      </item>
+
+      <tag><c><![CDATA[agent_originating_discovery_opts() = [agent_originating_discovery_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>agent_originating_discovery_opt() = 
+          {enable, boolean()}</c></p>
+        <p>These are options effecting discovery <c>originating</c> in this
+          agent. </p>
+        <p>The default values for the <c>originating</c> 
+          discovery options are: </p>
+        <list type="bulleted">
+          <item>enable: <c>true</c></item>
+        </list>
+      </item>
+
+      <tag><c><![CDATA[multi_threaded() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If <c>true</c>, the agent is multi-threaded, with one
+          thread for each get request. </p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[db_dir() = string() <mandatory>]]></c></tag>
+      <item>
+        <p>Defines where the SNMP agent internal db files are stored.</p>
+      </item>
+
+      <tag><c><![CDATA[local_db() = [local_db_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>local_db_opt() = {repair, agent_repair()} | {auto_save, agent_auto_save()} |   {verbosity, verbosity()}</c></p>
+        <p>Defines options specific for the SNMP agent local database.</p>
+        <p>For defaults see the options in <c>local_db_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_repair() = false | true | force <optional>]]></c></tag>
+      <item>
+        <p>When starting snmpa_local_db it always tries to open an
+          existing database. If <c>false</c>, and some errors occur, a new
+          database is created instead. If <c>true</c>, an existing file
+          will be repaired. If <c>force</c>, the table will be repaired
+          even if it was properly closed. </p>
+        <p>Default is <c>true</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_auto_save() = integer() | infinity <optional>]]></c></tag>
+      <item>
+        <p>The auto save interval. The table is flushed to disk
+          whenever not accessed for this amount of time.</p>
+        <p>Default is <c>5000</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_net_if() = [agent_net_if_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>agent_net_if_option() = {module, agent_net_if_module()} | 
+            {verbosity, verbosity()} | 
+            {options, agent_net_if_options()}</c></p>
+        <p>Defines options specific for the SNMP agent network interface 
+          entity. </p>
+        <p>For defaults see the options in <c>agent_net_if_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_net_if_module() = atom() <optional>]]></c></tag>
+      <item>
+        <p>Module which handles the network interface part for the
+          SNMP agent. Must implement the 
+          <seealso marker="snmpa_network_interface">snmpa_network_interface</seealso> behaviour.</p>
+        <p>Default is <c>snmpa_net_if</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag>
+      <item>
+        <p><c>agent_net_if_option() = {bind_to, bind_to()} |  
+            {sndbuf, sndbuf()} |  
+            {recbuf, recbuf()} |  
+            {no_reuse, no_reuse()} | 
+	    {req_limit, req_limit()} |
+            {filter, agent_net_if_filter_options()}</c></p>
+        <p>These options are actually specific to the used module.
+          The ones shown here are applicable to the default 
+          <c>agent_net_if_module()</c>.</p>
+        <p>For defaults see the options in <c>agent_net_if_option()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_net_if_filter_options() = [agent_net_if_filter_option()] <optional>]]></c></tag>
+      <item>
+	<p><c><![CDATA[agent_net_if_filter_option() = {module, agent_net_if_filter_module()}]]></c></p>
+	<p>These options are actually specific to the used module.
+	  The ones shown here are applicable to the default 
+	  <c>agent_net_if_filter_module()</c>.</p>
+	<p>For defaults see the options in <c>agent_net_if_filter_option()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_net_if_filter_module() = atom() <optional>]]></c></tag>
+      <item>
+	<p>Module which handles the network interface filter part for the
+	  SNMP agent. Must implement the 
+	  <seealso marker="snmpa_network_interface_filter">snmpa_network_interface_filter
+	    </seealso> behaviour.</p>
+	<p>Default is <c>snmpa_net_if_filter</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[req_limit() = integer() | infinity <optional>]]></c></tag>
+      <item>
+        <p>Max number of simultaneous requests handled by the agent.</p>
+        <p>Default is <c>infinity</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_mibs() = [string()] <optional>]]></c></tag>
+      <item>
+        <p>Specifies a list of MIBs (including path) that defines which MIBs
+          are initially loaded into the SNMP master agent. </p>
+        <p>Note that the following will always be loaded:</p>
+        <list type="bulleted">
+          <item>version v1: <c>STANDARD-MIB</c></item>
+          <item>version v2: <c>SNMPv2</c></item>
+          <item>version v3: <c>SNMPv2</c>, <c>SNMP-FRAMEWORK-MIB</c> 
+           and <c>SNMP-MPD-MIB</c></item>
+        </list>
+        <p>Default is <c>[]</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mib_storage() = ets | {ets, Dir} | {ets, Dir, Action} | dets | {dets, Dir} | {dets, Dir, Action} | mnesia | {mnesia, Nodes} | {mnesia, Nodes, Action} <optional>]]></c></tag>
+      <item>
+        <p>Specifies how info retrieved from the mibs will be stored.</p>
+        <p>If <c>mib_storage</c> is <c>{ets, Dir}</c>, the table will also be 
+          stored on file. If <c>Dir</c> is <c>default</c>, then <c>db_dir</c> 
+          will be used.</p>
+        <p>If <c>mib_storage</c> is <c>dets</c> or if <c>Dir</c> is 
+          <c>default</c>, then <c>db_dir</c> will be used for <c>Dir</c>.</p>
+        <p>If <c>mib_storage</c> is <c>mnesia</c> then <c>erlang:nodes()</c>
+          will be used for <c>Nodes</c>.</p>
+        <p>Default is <c>ets</c>. </p>
+        <p><c>Dir = default | string()</c>. Dir is the directory where the 
+          files will be stored. If <c>default</c>, then <c>db_dir</c> will be 
+          used.</p>
+        <p><c>Nodes = visible | connected | [node()]</c>. 
+          <c>Nodes = visible</c> is translated to 
+          <c>erlang:nodes(visible)</c>. 
+          <c>Nodes = connected</c> is translated to 
+          <c>erlang:nodes(connected)</c>. 
+          If <c>Nodes = []</c> then the own node is assumed.</p>
+        <p><c>Action = clear | keep</c>. Default is <c>keep</c>.
+          <c>Action</c> is used to specify what shall be done if the 
+          mnesia/dets table already exist.</p>
+      </item>
+
+      <tag><c><![CDATA[mib_server() = [mib_server_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>mib_server_opt() = {mibentry_override, mibentry_override()} |  {trapentry_override, trapentry_override()} |  {verbosity, verbosity()} | {cache, mibs_cache()}</c></p>
+        <p>Defines options specific for the SNMP agent mib server. </p>
+        <p>For defaults see the options in <c>mib_server_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mibentry_override() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If this value is false, then when loading a mib each mib-
+          entry is checked prior to installation of the mib. 
+          The purpose of the check is to prevent that the same symbolic 
+          mibentry name is used for different oid's.</p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[trapentry_override() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If this value is false, then when loading a mib each trap
+          is checked prior to installation of the mib. 
+          The purpose of the check is to prevent that the same symbolic 
+          trap name is used for different trap's.</p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mibs_cache() = bool() | mibs_cache_opts() <optional>]]></c></tag>
+      <item>
+        <p>Shall the agent utilize the mib server lookup cache or not.</p>
+        <p>Default is <c>true</c> (in which case the <c>mibs_cache_opts()</c> 
+          default values apply).</p>
+      </item>
+
+      <tag><c><![CDATA[mibs_cache_opts() = [mibs_cache_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>mibs_cache_opt() = {autogc, mibs_cache_autogc()} | {gclimit, mibs_cache_gclimit()} | {age, mibs_cache_age()}</c></p>
+        <p>Defines options specific for the SNMP agent mib server cache. </p>
+        <p>For defaults see the options in <c>mibs_cache_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mibs_cache_autogc() = bool() <optional>]]></c></tag>
+      <item>
+        <p>Defines if the mib server shall perform cache gc automatically or 
+          leave it to the user (see 
+          <seealso marker="snmpa#gc_mibs_cache">gc_mibs_cache/0,1,2,3</seealso>). </p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mibs_cache_age() = integer() > 0 <optional>]]></c></tag>
+      <item>
+        <p>Defines how old the entries in the cache will be allowed before 
+          they are GC'ed (assuming GC is performed). Each entry in the 
+          cache is "touched" whenever it is accessed. </p>
+        <p>The age is defined in milliseconds. </p>
+        <p>Default is <c>10 timutes</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[mibs_cache_gclimit() = integer() > 0 | infinity <optional>]]></c></tag>
+      <item>
+        <p>When performing a GC, this is the max number of cache entries 
+          that will be deleted from the cache. </p>
+        <p>The reason for having this limit is that if the cache is 
+          large, the GC can potentially take a long time, during which 
+          the agent is locked. </p>
+        <p>Default is <c>100</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[error_report_mod() = atom() <optional>]]></c></tag>
+      <item>
+        <p>Defines an error report module, implementing the 
+          <seealso marker="snmpa_error_report">snmpa_error_report</seealso> 
+          behaviour. Two modules are provided with the toolkit: 
+          <c>snmpa_error_logger</c> and <c>snmpa_error_io</c>.</p>
+        <p>Default is <c>snmpa_error_logger</c>.</p>
+      </item>
+
+      <tag><c>symbolic_store() = [symbolic_store_opt()]</c></tag>
+      <item>
+        <p><c>symbolic_store_opt() = {verbosity, verbosity()}</c></p>
+        <p>Defines options specific for the SNMP agent symbolic store. </p>
+        <p>For defaults see the options in <c>symbolic_store_opt()</c>.</p>
+      </item>
+
+      <tag><c>target_cache() = [target_cache_opt()]</c></tag>
+      <item>
+        <p><c>target_cache_opt() = {verbosity, verbosity()}</c></p>
+        <p>Defines options specific for the SNMP agent target cache. </p>
+        <p>For defaults see the options in <c>target_cache_opt()</c>.</p>
+      </item>
+      <tag><c><![CDATA[agent_config() = [agent_config_opt()] <mandatory>]]></c></tag>
+      <item>
+        <p><c>agent_config_opt() = {dir, agent_config_dir()} |  {force_load, force_load()} | {verbosity, verbosity()}</c></p>
+        <p>Defines specific config related options for the SNMP agent. </p>
+        <p>For defaults see the options in <c>agent_config_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag>
+      <item>
+        <p>Defines where the SNMP agent configuration files are stored.</p>
+      </item>
+
+      <tag><c><![CDATA[force_load() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If <c>true</c> the configuration files are re-read
+          during start-up, and the contents of the configuration 
+          database ignored.  Thus, if <c>true</c>, changes to 
+          the configuration database are lost upon reboot of the 
+          agent. </p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+    </taglist>
+
+    <p>Manager specific config options and types:</p>
+    <taglist>
+      <tag><c><![CDATA[server() = [server_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>server_opt() = {timeout, server_timeout()} |  {verbosity, verbosity()}</c></p>
+        <p>Specifies the options for the manager server process.</p>
+        <p>Default is <c>silence</c>.</p>
+      </item>
+      <tag><c><![CDATA[server_timeout() = integer() <optional>]]></c></tag>
+      <item>
+        <p>Asynchroneous request cleanup time. For every requests, 
+          some info is stored internally, in order to be able to 
+          deliver the reply (when it arrives) to the proper destination.
+          If the reply arrives, this info will be deleted. But if
+          there is no reply (in time), the info has to be deleted
+          after the <em>best before</em> time has been passed.
+          This cleanup will be performed at regular intervals, defined 
+          by the <c>server_timeout()</c> time.
+          The information will have a <em>best before</em> time,
+          defined by the <c>Expire</c> time given when calling the
+          request function (see 
+          <seealso marker="snmpm#async_get">async_get</seealso>,
+          <seealso marker="snmpm#async_get_next">async_get_next</seealso> and 
+          <seealso marker="snmpm#async_set">async_set</seealso>).</p>
+        <p>Time in milli-seconds.</p>
+        <p>Default is <c>30000</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag>
+      <item>
+        <p><c>manager_config_opt() = {dir, manager_config_dir()} |  {db_dir, manager_db_dir()} |  {db_init_error, db_init_error()} |  {repair, manager_repair()} |  {auto_save, manager_auto_save()} |  {verbosity, verbosity()}</c></p>
+        <p>Defines specific config related options for the SNMP manager. </p>
+        <p>For defaults see the options in <c>manager_config_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag>
+      <item>
+        <p>Defines where the SNMP manager configuration files are stored.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag>
+      <item>
+        <p>Defines where the SNMP manager store persistent data.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_repair() = false | true | force <optional>]]></c></tag>
+      <item>
+        <p>Defines the repair option for the persistent database (if 
+          and how the table is repaired when opened). </p>
+        <p>Default is <c>true</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_auto_save() = integer() | infinity <optional>]]></c></tag>
+      <item>
+        <p>The auto save interval. The table is flushed to disk
+          whenever not accessed for this amount of time.</p>
+        <p>Default is <c>5000</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_irb() = auto | user | {user, integer()} <optional>]]></c></tag>
+      <item>
+        <p>This option defines how the manager will handle the sending of 
+          response (acknowledgment) to received inform-requests. </p>
+        <list type="bulleted">
+          <item>
+            <p><c>auto</c> - The manager will autonomously send response
+              (acknowledgment&gt; to inform-request messages.</p>
+          </item>
+          <item>
+            <p><c>{user, integer()}</c> - The manager will send response
+              (acknowledgment) to inform-request messages when the 
+              <seealso marker="snmpm_user#handle_inform">handle_inform</seealso> 
+              function completes. The integer is the time, in milli-seconds, 
+              that the manager will consider the stored inform-request info 
+              valid.</p>
+          </item>
+          <item>
+            <p><c>user</c> - Same as <c>{user, integer()}</c>, except that 
+              the default time, 15000 milli-seconds, is used.</p>
+          </item>
+        </list>
+        <p>See 
+          <seealso marker="snmpm_network_interface">snmpm_network_interface</seealso>, 
+          <seealso marker="snmpm_user">handle_inform</seealso> and 
+          <seealso marker="snmp_manager_netif">definition of the manager net if</seealso> for more info.</p>
+        <p>Default is <c>auto</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_mibs() = [string()] <optional>]]></c></tag>
+      <item>
+        <p>Specifies a list of MIBs (including path) and defines which MIBs
+          are initially loaded into the SNMP manager. </p>
+        <p>Default is <c>[]</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_net_if() = [manager_net_if_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>manager_net_if_opt() = {module, manager_net_if_module()} | 
+          {verbosity, verbosity()} | 
+          {options, manager_net_if_options()}</c></p>
+        <p>Defines options specific for the SNMP manager network interface 
+          entity. </p>
+        <p>For defaults see the options in <c>manager_net_if_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_net_if_options() = [manager_net_if_option()] <optional>]]></c></tag>
+      <item>
+        <p><c>manager_net_if_option() = {bind_to, bind_to()} | 
+          {sndbuf, sndbuf()} | 
+          {recbuf, recbuf()} | 
+          {no_reuse, no_reuse()} |
+          {filter, manager_net_if_filter_options()}</c></p>
+        <p>These options are actually specific to the used module.
+          The ones shown here are applicable to the default 
+          <c>manager_net_if_module()</c>.</p>
+        <p>For defaults see the options in <c>manager_net_if_option()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag>
+      <item>
+        <p>Module which handles the network interface part for the
+          SNMP manager. Must implement the 
+          <seealso marker="snmpm_network_interface">snmpm_network_interface</seealso> behaviour.</p>
+        <p>Default is <c>snmpm_net_if</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_net_if_filter_options() = [manager_net_if_filter_option()] <optional>]]></c></tag>
+      <item>
+	<p><c>manager_net_if_filter_option() = {module, manager_net_if_filter_module()}</c></p>
+	<p>These options are actually specific to the used module.
+	  The ones shown here are applicable to the default 
+	  <c><![CDATA[manager_net_if_filter_module()]]></c>.</p>
+	<p>For defaults see the options in 
+          <c>manager_net_if_filter_option()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[manager_net_if_filter_module() = atom() <optional>]]></c></tag>
+      <item>
+	<p>Module which handles the network interface filter part for the
+	  SNMP manager. Must implement the 
+	  <seealso marker="snmpm_network_interface_filter">snmpm_network_interface_filter</seealso> behaviour.</p>
+	<p>Default is <c>snmpm_net_if_filter</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[def_user_module() = atom() <optional>]]></c></tag>
+      <item>
+        <p>The module implementing the default user. See the 
+          <seealso marker="snmpm_user">snmpm_user</seealso> behaviour.</p>
+        <p>Default is <c>snmpm_user_default</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[def_user_data() = term() <optional>]]></c></tag>
+      <item>
+        <p>Data for the default user. Passed to the user when calling 
+          the callback functions.</p>
+        <p>Default is <c>undefined</c>.</p>
+      </item>
+    </taglist>
+
+    <p>Common config types:</p>
+    <taglist>
+      <tag><c>restart_type() = permanent | transient | temporary</c></tag>
+      <item>
+        <p>See <seealso marker="stdlib:supervisor#child_spec">supervisor</seealso> 
+          documentation for more info.</p>
+        <p>Default is <c>permanent</c> for the agent and <c>transient</c>
+          for the manager.</p>
+      </item>
+
+      <tag><c>db_init_error() = terminate | create</c></tag>
+      <item>
+        <p>Defines what to do if the agent is unable to open an
+          existing database file. <c>terminate</c> means that the
+          agent/manager will terminate and <c>create</c> means that the 
+          agent/manager will remove the faulty file(s) and create new ones.</p>
+        <p>Default is <c>terminate</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[priority() = atom() <optional>]]></c></tag>
+      <item>
+        <p>Defines the Erlang priority for all SNMP processes.</p>
+        <p>Default is <c>normal</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[versions() = [version()] <optional>]]></c></tag>
+      <item>
+        <p><c>version() = v1 | v2 | v3</c></p>
+        <p>Which SNMP versions shall be accepted/used.</p>
+        <p>Default is <c>[v1,v2,v3]</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[verbosity() = silence | info | log | debug | trace <optional>]]></c></tag>
+      <item>
+        <p>Verbosity for a SNMP process. This specifies now much debug info
+          is printed.</p>
+        <p>Default is <c>silence</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[bind_to() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If <c>true</c>, net_if binds to the IP address.
+          If <c>false</c>, net_if listens on any IP address on the host
+          where it is running. </p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[no_reuse() = bool() <optional>]]></c></tag>
+      <item>
+        <p>If <c>true</c>, net_if does not specify that the IP
+          and port address should be reusable. If <c>false</c>, 
+          the address is set to reusable. </p>
+        <p>Default is <c>false</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[recbuf() = integer() <optional>]]></c></tag>
+      <item>
+        <p>Receive buffer size. </p>
+        <p>Default value is defined by <c>gen_udp</c>.</p>
+      </item>
+      <tag><c><![CDATA[sndbuf() = integer() <optional>]]></c></tag>
+      <item>
+        <p>Send buffer size. </p>
+        <p>Default value is defined by <c>gen_udp</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[note_store() = [note_store_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>note_store_opt() = {timeout, note_store_timeout()} |  {verbosity, verbosity()}</c></p>
+        <p>Specifies the options for the SNMP note store.</p>
+        <p>For defaults see the options in <c>note_store_opt()</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[note_store_timeout() = integer() <optional>]]></c></tag>
+      <item>
+        <p>Note cleanup time. When storing a note in the note store,
+          each note is given lifetime. Every <c>timeout</c> the note_store
+          process performs a GC to remove the expired note's. Time in
+          milli-seconds.</p>
+        <p>Default is <c>30000</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[audit_trail_log() [audit_trail_log_opt()] <optional>]]></c></tag>
+      <item>
+        <p><c>audit_trail_log_opt() = {type, atl_type()} | {dir, atl_dir()} |  {size, atl_size()} |  {repair, atl_repair()}</c></p>
+        <p>If present, this option specifies the options for the 
+          <em>audit trail logging</em>. The <c>disk_log</c> module is used 
+          to maintain a wrap log. If present, the <c>dir</c> and 
+          <c>size</c> options are mandatory.</p>
+        <p>If not present, audit trail logging is not used.</p>
+      </item>
+
+      <tag><c><![CDATA[atl_type() = read | write | read_write <optional>]]></c></tag>
+      <item>
+        <p>Specifies what type of an audit trail log should be used. 
+          The effect of the type is actually different for the the agent
+          and the manager. </p>
+        <p>For the agent:</p>
+        <list type="bulleted">
+          <item>If <c>write</c> is specified, only set requests are logged.  </item>
+          <item>If <c>read</c> is specified, only get requests are logged.  </item>
+          <item>If <c>read_write</c>, all requests are logged.  </item>
+        </list>
+        <p>For the manager:</p>
+        <list type="bulleted">
+          <item>If <c>write</c> is specified, only sent messages are logged.  </item>
+          <item>If <c>read</c> is specified, only received messages are logged.  </item>
+          <item>If <c>read_write</c>, both outgoing and incoming messages are 
+           logged.  </item>
+        </list>
+        <p>Default is <c>read_write</c>.</p>
+      </item>
+
+      <tag><c><![CDATA[atl_dir = dir() <mandatory>]]></c></tag>
+      <item>
+        <p>Specifies where the audit trail log should be stored.</p>
+        <p>If <c>audit_trail_log</c> specifies that logging should take
+          place, this parameter <em>must</em> be defined.</p>
+      </item>
+
+      <tag><c><![CDATA[atl_size() = {integer(), integer()} <mandatory>]]></c></tag>
+      <item>
+        <p>Specifies the size of the audit
+          trail log.  This parameter is sent to <c>disk_log</c>.  </p>
+        <p>If <c>audit_trail_log</c> specifies that logging should 
+          take place, this parameter <em>must</em> be defined.</p>
+      </item>
+
+      <tag><c><![CDATA[atl_repair() = true | false | truncate | snmp_repair <optional>]]></c></tag>
+      <item>
+        <p>Specifies if and how the audit trail log shall be repaired
+          when opened. Unless this parameter has the value <c>snmp_repair</c>
+          it is sent to <c>disk_log</c>. If, on the other hand, the value is
+          <c>snmp_repair</c>, snmp attempts to handle certain faults on it's 
+          own. And even if it cannot repair the file, it does not truncate it 
+          directly, but instead <em>moves it aside</em> for later off-line 
+          analysis.</p>
+        <p>Default is <c>true</c>.</p>
+      </item>
+    </taglist>
+  </section>
+
+  <section>
+    <title>Modifying the Configuration Files</title>
+    <p>To to start the application (agent and/or manager), the 
+      configuration files must be modified and there are two ways 
+      of doing this. Either edit the files manually, or run the 
+      configuration tool as follows.</p>
+    <p>If authentication or encryption is used (SNMPv3 only), start
+      the <c>crypto</c> application.</p>
+    <pre>
+1> snmp:config().
+
+Simple SNMP configuration tool (version 4.0)
+------------------------------------------------
+Note: Non-trivial configurations still has to be
+      done manually. IP addresses may be entered 
+      as dront.ericsson.se (UNIX only) or
+      123.12.13.23
+------------------------------------------------
+
+Configure an agent (y/n)? [y] 
+
+Agent system config: 
+--------------------
+1. Agent process priority (low/normal/high) [normal] 
+2. What SNMP version(s) should be used (1,2,3,1&amp;2,1&amp;2&amp;3,2&amp;3)? [3] 1&amp;2&amp;3
+3. Configuration directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/agent/conf
+4. Config verbosity (silence/info/log/debug/trace)? [silence] 
+5. Database directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/agent/db
+6. Mib storage type (ets/dets/mnesia)? [ets] 
+7. Target cache verbosity (silence/info/log/debug/trace)? [silence] 
+8. Symbolic store verbosity (silence/info/log/debug/trace)? [silence] 
+9. Local DB verbosity (silence/info/log/debug/trace)? [silence] 
+10. Local DB repair (true/false/force)? [true] 
+11. Local DB auto save (infinity/milli seconds)? [5000] 
+12. Error report module? [snmpa_error_logger] 
+13. Agent type (master/sub)? [master] 
+14. Master-agent verbosity (silence/info/log/debug/trace)? [silence] log
+15. Shall the agent re-read the configuration files during startup 
+    (and ignore the configuration database) (true/false)? [true] 
+16. Multi threaded agent (true/false)? [false] true
+17. Check for duplicate mib entries when installing a mib (true/false)? [false] 
+18. Check for duplicate trap names when installing a mib (true/false)? [false] 
+19. Mib server verbosity (silence/info/log/debug/trace)? [silence] 
+20. Mib server cache (true/false)? [true]
+21. Note store verbosity (silence/info/log/debug/trace)? [silence] 
+22. Note store GC timeout? [30000] 
+23. Shall the agent use an audit trail log (y/n)? [n] y
+23b. Audit trail log type (write/read_write)? [read_write] 
+23c. Where to store the audit trail log? [/ldisk/snmp] /ldisk/snmp/agent/log
+23d. Max number of files? [10] 
+23e. Max size (in bytes) of each file? [10240] 
+23f. Audit trail log repair (true/false/truncate)? [true] 
+24. Which network interface module shall be used? [snmpa_net_if] 
+25. Network interface verbosity (silence/info/log/debug/trace)? [silence] log
+25a. Bind the agent IP address (true/false)? [false] 
+25b. Shall the agents IP address and port be not reusable (true/false)? [false] 
+25c. Agent request limit (used for flow control) (infinity/pos integer)? [infinity] 32
+25d. Receive buffer size of the agent (in bytes) (default/pos integer)? [default] 
+25e. Send buffer size of the agent (in bytes) (default/pos integer)? [default]
+25f. Do you wish to specify a network interface filter module (or use default) [default] 
+
+Agent snmp config: 
+------------------
+1. System name (sysName standard variable) [bmk's agent] 
+2. Engine ID (snmpEngineID standard variable) [bmk's engine] 
+3. Max message size? [484] 
+4. The UDP port the agent listens to. (standard 161) [4000] 
+5. IP address for the agent (only used as id 
+   when sending traps) [127.0.0.1] 
+6. IP address for the manager (only this manager 
+   will have access to the agent, traps are sent 
+   to this one) [127.0.0.1] 
+7. To what UDP port at the manager should traps 
+   be sent (standard 162)? [5000] 
+8. Do you want a none- minimum- or semi-secure configuration? 
+   Note that if you chose v1 or v2, you won't get any security for these
+   requests (none, minimum, semi_des, semi_aes) [minimum] 
+making sure crypto server is started...
+8b. Give a password of at least length 8. It is used to generate 
+    private keys for the configuration:  kalle-anka
+9. Current configuration files will now be overwritten. Ok (y/n)? [y] 
+
+- - - - - - - - - - - - -
+Info: 1. SecurityName "initial" has noAuthNoPriv read access
+         and authenticated write access to the "restricted"
+         subtree.
+      2. SecurityName "all-rights" has noAuthNoPriv read/write
+         access to the "internet" subtree.
+      3. Standard traps are sent to the manager.
+      4. Community "public" is mapped to security name "initial".
+      5. Community "all-rights" is mapped to security name "all-rights".
+The following agent files were written: agent.conf, community.conf,
+standard.conf, target_addr.conf, target_params.conf, 
+notify.conf, vacm.conf and usm.conf
+- - - - - - - - - - - - -
+
+Configure a manager (y/n)? [y] 
+
+Manager system config: 
+----------------------
+1. Manager process priority (low/normal/high) [normal] 
+2. What SNMP version(s) should be used (1,2,3,1&amp;2,1&amp;2&amp;3,2&amp;3)? [3] 1&amp;2&amp;3
+3. Configuration directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/manager/conf
+4. Config verbosity (silence/info/log/debug/trace)? [silence] log
+5. Database directory (absolute path)? [/ldisk/snmp] /ldisk/snmp/manager/db
+6. Database repair (true/false/force)? [true] 
+7. Database auto save (infinity/milli seconds)? [5000] 
+8. Inform request behaviour (auto/user)? [auto] 
+9. Server verbosity (silence/info/log/debug/trace)? [silence] log
+10. Server GC timeout? [30000] 
+11. Note store verbosity (silence/info/log/debug/trace)? [silence] 
+12. Note store GC timeout? [30000] 
+13. Which network interface module shall be used? [snmpm_net_if] 
+14. Network interface verbosity (silence/info/log/debug/trace)? [silence] log
+15. Bind the manager IP address (true/false)? [false] 
+16. Shall the manager IP address and port be not reusable (true/false)? [false] 
+17. Receive buffer size of the manager (in bytes) (default/pos integer)? [default] 
+18. Send buffer size of the manager (in bytes) (default/pos integer)? [default] 
+19. Shall the manager use an audit trail log (y/n)? [n] y
+19b. Where to store the audit trail log? [/ldisk/snmp] /ldisk/snmp/manager/log
+19c. Max number of files? [10] 
+19d. Max size (in bytes) of each file? [10240] 
+19e. Audit trail log repair (true/false/truncate)? [true] 
+20. Do you wish to assign a default user [yes] or use
+    the default settings [no] (y/n)? [n] 
+
+Manager snmp config: 
+--------------------
+1. Engine ID (snmpEngineID standard variable) [bmk's engine] 
+2. Max message size? [484] 
+3. IP address for the manager (only used as id 
+   when sending requests) [127.0.0.1] 
+4. Port number (standard 162)? [5000] 
+5. Configure a user of this manager (y/n)? [y] 
+5b. User id? kalle
+5c. User callback module? snmpm_user_default
+5d. User (callback) data? [undefined] 
+5. Configure a user of this manager (y/n)? [y] n
+6. Configure an agent handled by this manager (y/n)? [y] 
+6b. User id? kalle
+6c. Target name? [bmk's agent] 
+6d. Version (1/2/3)? [1] 3
+6e. Community string ? [public] 
+6f. Engine ID (snmpEngineID standard variable) [bmk's engine] 
+6g. IP address for the agent [127.0.0.1] 
+6h. The UDP port the agent listens to. (standard 161) [4000] 
+6i. Retransmission timeout (infinity/pos integer)? [infinity] 
+6j. Max message size? [484] 
+6k. Security model (any/v1/v2c/usm)? [any] usm
+6l. Security name? ["initial"] 
+6m. Security level (noAuthNoPriv/authNoPriv/authPriv)? [noAuthNoPriv] authPriv
+6. Configure an agent handled by this manager (y/n)? [y] n
+7. Configure an usm user handled by this manager (y/n)? [y] 
+7a. Engine ID [bmk's engine] 
+7b. User name? hobbes
+7c. Security name? [hobbes] 
+7d. Authentication protocol (no/sha/md5)? [no] sha
+7e  Authentication [sha] key (length 0 or 20)? [""] [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]
+7d. Priv protocol (no/des/aes)? [no] des
+7f  Priv [des] key (length 0 or 16)? [""] 10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25
+7. Configure an usm user handled by this manager (y/n)? [y] n
+8. Current configuration files will now be overwritten. Ok (y/n)? [y] 
+
+- - - - - - - - - - - - -
+The following manager files were written: manager.conf, agents.conf , users.conf and usm.conf
+- - - - - - - - - - - - -
+
+--------------------
+Configuration directory for system file (absolute path)? [/ldisk/snmp] 
+ok
+    </pre>
+  </section>
+
+  <section>
+    <title>Starting the application</title>
+    <p>Start Erlang with the command:</p>
+    <code type="none">
+erl -config /tmp/snmp/sys
+    </code>
+    <p>If authentication or encryption is used (SNMPv3 only), start
+      the <c>crypto</c> application.  If this step is forgotten, the
+      agent will not start, but report a
+      <c>{config_error,{unsupported_crypto,_}}</c> error.</p>
+    <pre>
+1> <input>application:start(crypto).</input>
+ok
+    </pre>
+    <pre>
+2> <input>application:start(snmp).</input>
+ok
+    </pre>
+  </section>
+
+  <section>
+    <marker id="verbosity"></marker>
+    <title>Debugging the application</title>
+    <p>It is possible to debug every (non-supervisor) process of the 
+      application (both agent and manager), possibly with the exception 
+      of the net_if module(s), which could be supplied by a user of the 
+      application). This is done by calling the 
+      <c>snmpa:verbosity/2</c> and <c>snmpm:verbosity/2</c> function(s) 
+      and/or using 
+      <seealso marker="#configuration_params">configuration parameters</seealso>.
+      The verbosity itself has several <em>levels</em>: <c>silence | info |  log | debug | trace</c>. For the lowest verbosity <c>silence</c>, 
+      nothing is printed. The higher the verbosity, the more is printed.
+      Default value is always <c>silence</c>.</p>
+    <pre>
+3> <input>snmpa:verbosity(master_agent, log).</input>
+ok
+5> <input>snmpa:verbosity(net_if, log).</input>
+ok
+6> 
+%% Example of output from the agent when a get-next-request arrives:
+** SNMP NET-IF LOG: 
+   got packet from {147,12,12,12}:5000
+
+** SNMP NET-IF MPD LOG: 
+   v1, community: all-rights
+
+** SNMP NET-IF LOG: 
+   got pdu from {147,12,12,12}:5000 {pdu, 'get-next-request',
+                                          62612569,noError,0,
+                                          [{varbind,[1,1],'NULL','NULL',1}]}
+
+** SNMP MASTER-AGENT LOG: 
+   apply: snmp_generic,variable_func,[get,{sysDescr,persistent}]
+
+** SNMP MASTER-AGENT LOG: 
+   returned: {value,"Erlang SNMP agent"}
+
+** SNMP NET-IF LOG: 
+   reply pdu: {pdu,'get-response',62612569,noError,0,
+                   [{varbind,[1,3,6,1,2,1,1,1,0],
+                             'OCTET STRING',
+                             "Erlang SNMP agent",1}]}
+
+** SNMP NET-IF INFO: time in agent: 19711 mysec
+    </pre>
+
+    <p>Other useful function(s) for debugging the agent are: </p>
+    <taglist>
+      <tag><c><![CDATA[snmpa:info/0,1]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#info">info</seealso> is used to retrieve a list of miscellaneous agent information.</p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:which_aliasnames/0]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#which_aliasnames">which_aliasnames</seealso> is used to retrieve a list of all alias-names known to the agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:which_tables/0]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#which_tables">which_tables</seealso> is used to retrieve a list of all (MIB) tables known to the agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:which_variables/0]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#which_variables">which_variables</seealso> is used to retrieve a list of all (MIB) variables known to the agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:which_notifications/0]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#which_notifications">which_notifications</seealso> is used to retrieve a list of all (MIB) notifications/traps known to the agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:restart_worker/0,1]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#restart_worker">restart_worker</seealso> is used to restart the worker process of a multi-threaded agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa:restart_set_worker/0,1]]></c></tag>
+      <item>
+        <p><seealso marker="snmpa#restart_set_worker">restart_set_worker</seealso> is used to restart the set-worker process of a multi-threaded agent. </p>
+      </item>
+
+      <tag><c><![CDATA[snmpa_local_db:print/0,1,2]]></c></tag>
+      <item>
+        <p>For example, this function can show the counters 
+          <c>snmpInPkts</c> and <c>snmpOutPkts</c>.</p>
+      </item>
+    </taglist>
+
+    <p>Another usefull way to debug the agent is to pretty-print the content of 
+      some of the (MIB-) tables handled directly by the agent. This can be done 
+      for the following tables: </p>
+    <taglist>
+      <tag><c><![CDATA[snmpCommunityTable]]></c></tag>
+      <item>
+        <p><c><![CDATA[snmp_community_mib:snmpCommunityTable(print).]]></c></p>
+      </item>
+
+      <tag><c><![CDATA[snmpNotifyTable]]></c></tag>
+      <item>
+        <p><c><![CDATA[snmp_notification_mib:snmpNotifyTable(print).]]></c></p>
+      </item>
+
+      <tag><c><![CDATA[snmpTargetAddrTable]]></c></tag>
+      <item>
+        <p><c><![CDATA[snmp_target_mib:snmpTargetAddrTable(print).]]></c></p>
+      </item>
+
+      <tag><c><![CDATA[snmpTargetParamsTable]]></c></tag>
+      <item>
+        <p><c><![CDATA[snmp_target_mib:snmpTargetParamsTable(print).]]></c></p>
+      </item>
+
+      <tag><c><![CDATA[usmUserTable]]></c></tag>
+      <item>
+        <p><c><![CDATA[snmp_user_based_sm_mib:usmUserTable(print).]]></c></p>
+      </item>
+
+    </taglist>
+
+  </section>
+</chapter>
+