<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>1997</year><year>2013</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> <!-- ***************************************************** The info below is also found in the snmp_app.xml file ***************************************************** --> <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> <pre> agent_options() = [agent_option()] agent_option() = {restart_type, restart_type()} | {agent_type, agent_type()} | {agent_verbosity, verbosity()} | {versions, versions()} | {discovery, agent_discovery()} | {gb_max_vbs, gb_max_vbs()} | {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> <marker id="agent_opts_and_types"></marker> <p>Agent specific config options and types:</p> <taglist> <marker id="agent_type"></marker> <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> <marker id="agent_disco"></marker> <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> <marker id="agent_term_disco_opts"></marker> <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> <marker id="agent_orig_disco_opts"></marker> <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> <marker id="agent_mt"></marker> <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> <marker id="agent_data_dir"></marker> <tag><c><![CDATA[db_dir() = string() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent internal db files are stored.</p> </item> <marker id="agent_gb_max_vbs"></marker> <tag><c><![CDATA[gb_max_vbs() = pos_integer() | infinity <optional>]]></c></tag> <item> <p>Defines the maximum number of varbinds allowed in a Get-BULK response.</p> <p>Default is <c>1000</c>.</p> </item> <marker id="agent_local_db"></marker> <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> <marker id="agent_ldb_repair"></marker> <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> <marker id="agent_ldb_auto_save"></marker> <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> <marker id="agent_net_if"></marker> <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> <marker id="agent_ni_module"></marker> <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> <marker id="agent_ni_opts"></marker> <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> <marker id="agent_ni_req_limit"></marker> <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> <marker id="agent_ni_filter_opts"></marker> <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> <marker id="agent_ni_filter_module"></marker> <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> <marker id="agent_mibs"></marker> <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> <marker id="agent_mib_storage"></marker> <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> <marker id="agent_mib_server"></marker> <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()} | {data_module, mib_data_module()}</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> <marker id="agent_ms_meo"></marker> <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> <marker id="agent_ms_teo"></marker> <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> <marker id="agent_ms_data_module"></marker> <!-- <tag><c><![CDATA[mib_data_module() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag> --> <tag><c><![CDATA[mib_data_module() = snmpa_mib_data_tttn | module() <optional>]]></c></tag> <item> <p>Defines the backend mib_data storage module of the SNMP agent mib-server as defined by the <seealso marker="snmpa_mib_data">snmpa_mib_data</seealso> behaviour. </p> <p>At present only the default module is provided with the agent, <c>snmpa_mib_data_tttn</c>. </p> <!-- <p>Two modules is provided with the agent <c>snmpa_mib_data_tttn</c> (this is the old implementation) and <c>snmpa_mib_data_ttln</c> (for a mib tree with many holes, this algorithm can be more price efficient). </p> --> <p>Default module is <c>snmpa_mib_data_tttn</c>. </p> </item> <marker id="agent_ms_cache"></marker> <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> <marker id="agent_ms_cache_opts"></marker> <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> <marker id="agent_ms_cache_autogc"></marker> <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>true</c>.</p> </item> <marker id="agent_ms_cache_age"></marker> <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> <marker id="agent_ms_cache_gclimit"></marker> <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> <marker id="agent_error_report_mod"></marker> <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> <marker id="agent_symbolic_store"></marker> <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> <marker id="agent_target_cache"></marker> <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> <marker id="agent_config"></marker> <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> <marker id="agent_config_dir"></marker> <tag><c><![CDATA[agent_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP agent configuration files are stored.</p> </item> <marker id="agent_force_load"></marker> <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> <marker id="manager_opts_and_types"></marker> <p>Manager specific config options and types:</p> <taglist> <marker id="manager_server"></marker> <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> <marker id="manager_server_timeout"></marker> <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> <marker id="manager_config"></marker> <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> <marker id="manager_config_dir"></marker> <tag><c><![CDATA[manager_config_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager configuration files are stored.</p> </item> <marker id="manager_config_db_dir"></marker> <tag><c><![CDATA[manager_db_dir = dir() <mandatory>]]></c></tag> <item> <p>Defines where the SNMP manager store persistent data.</p> </item> <marker id="manager_config_repair"></marker> <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> <marker id="manager_config_auto_save"></marker> <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> <marker id="manager_irb"></marker> <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> 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> <marker id="manager_mibs"></marker> <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> <marker id="manager_net_if"></marker> <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> <marker id="manager_ni_opts"></marker> <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> <marker id="manager_ni_module"></marker> <tag><c><![CDATA[manager_net_if_module() = atom() <optional>]]></c></tag> <item> <p>The module which handles the network interface part for the SNMP manager. It must implement the <seealso marker="snmpm_network_interface">snmpm_network_interface</seealso> behaviour. </p> <p>Default is <c>snmpm_net_if</c>. </p> </item> <marker id="manager_ni_filter_opts"></marker> <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> <marker id="manager_ni_filter_module"></marker> <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> <marker id="manager_def_user_module"></marker> <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> <marker id="manager_def_user_data"></marker> <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> <marker id="common_types"></marker> <p>Common config types:</p> <taglist> <marker id="restart_type"></marker> <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> <marker id="db_init_error"></marker> <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> <marker id="prio"></marker> <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> <marker id="versions"></marker> <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> <marker id="verbosity"></marker> <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> <marker id="bind_to"></marker> <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> <marker id="no_reuse"></marker> <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> <marker id="recbuf"></marker> <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> <marker id="sndbuf"></marker> <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> <marker id="note_store"></marker> <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> <marker id="ns_timeout"></marker> <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> <marker id="audit_trail_log"></marker> <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()} | {seqno, atl_seqno()}</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> <marker id="atl_type"></marker> <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> <marker id="atl_dir"></marker> <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> <marker id="atl_size"></marker> <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> <marker id="atl_repair"></marker> <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 its 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> <marker id="atl_seqno"></marker> <tag><c><![CDATA[atl_seqno() = true | false <optional>]]></c></tag> <item> <p>Specifies if the audit trail log entries will be (sequence) numbered or not. The range of the sequence numbers are according to RFC 5424, i.e. 1 through 2147483647. </p> <p>Default is <c>false</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&2,1&2&3,2&3)? [3] 1&2&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&2,1&2&3,2&3)? [3] 1&2&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 all the tables and/or variables handled directly by the agent. This can be done by simply calling: </p> <p><c><![CDATA[snmpa:print_mib_info()]]></c></p> <p>See <seealso marker="snmpa#print_mib_info">print_mib_info/0</seealso>, <seealso marker="snmpa#print_mib_tables">print_mib_tables/0</seealso> or <seealso marker="snmpa#print_mib_variables">print_mib_variables/0</seealso> for more info. </p> </section> </chapter>