aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src/snmp.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/snmp/doc/src/snmp.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/snmp/doc/src/snmp.xml')
-rw-r--r--lib/snmp/doc/src/snmp.xml608
1 files changed, 608 insertions, 0 deletions
diff --git a/lib/snmp/doc/src/snmp.xml b/lib/snmp/doc/src/snmp.xml
new file mode 100644
index 0000000000..af0833f005
--- /dev/null
+++ b/lib/snmp/doc/src/snmp.xml
@@ -0,0 +1,608 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</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>snmp</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>snmp.xml</file>
+ </header>
+ <module>snmp</module>
+ <modulesummary>Interface functions to the SNMP toolkit</modulesummary>
+ <description>
+ <p>The module <c>snmp</c> contains interface functions to the
+ SNMP toolkit.</p>
+ </description>
+
+ <section>
+ <title>Common Data Types</title>
+ <p>The following data-types are used in the functions below: </p>
+ <list type="bulleted">
+ <item>
+ <p><c>datetime() = {date(), time()}</c></p>
+ <p>See <seealso marker="stdlib:calendar">calendar</seealso>
+ for more info.</p>
+ </item>
+
+ </list>
+
+ <marker id="config"></marker>
+ </section>
+
+ <funcs>
+ <func>
+ <name>config() -> ok | {error, Reason}</name>
+ <fsummary>Configure with a simple interactive tool</fsummary>
+ <desc>
+ <p>A simple interactive configuration tool. Simple
+ configuration files can be generated, but more complex
+ configurations still have to be edited manually.
+ </p>
+ <p>The tool is a textual based tool that asks some questions
+ and generates <c>sys.config</c> and <c>*.conf</c> files.
+ </p>
+ <p><em>Note</em> that if the application shall support version 3,
+ then the crypto app must be started before running this function
+ (password generation).</p>
+ <p><em>Note</em> also that some of the configuration files for the
+ agent and manager share the same names. This means that
+ they have to be stored in <em>different</em> directories!</p>
+
+ <marker id="start"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>start() -> ok | {error, Reason}</name>
+ <name>start(Type) -> ok | {error, Reason}</name>
+ <fsummary>Start the SNMP application</fsummary>
+ <type>
+ <v>Type = start_type()</v>
+ </type>
+ <desc>
+ <p>Starts the SNMP application.</p>
+ <p>See <seealso marker="kernel:application">application</seealso> for more info.</p>
+
+ <marker id="start_agent"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>start_agent() -> ok | {error, Reason}</name>
+ <name>start_agent(Type) -> ok | {error, Reason}</name>
+ <fsummary>Start the agent part of the SNMP application</fsummary>
+ <type>
+ <v>Type = start_type()</v>
+ </type>
+ <desc>
+ <p>The SNMP application consists of several entities, of which the
+ agent is one. This function starts the agent entity of the
+ application.
+ </p>
+ <p>Note that the only way to actually start the agent in this way is
+ to add the agent related config after starting the application (e.g
+ it cannot be part of the normal application config; sys.config).
+ This is done by calling:
+ <c>application:set_env(snmp, agent, Conf)</c>.
+ </p>
+ <p>The default value for <c>Type</c> is <c>normal</c>.</p>
+
+ <marker id="start_manager"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>start_manager() -> ok | {error, Reason}</name>
+ <name>start_manager(Type) -> ok | {error, Reason}</name>
+ <fsummary>Start the manager part of the SNMP application</fsummary>
+ <type>
+ <v>Type = start_type()</v>
+ </type>
+ <desc>
+ <p>The SNMP application consists of several entities, of which the
+ manager is one. This function starts the manager entity of the
+ application.
+ </p>
+ <p>Note that the only way to actually start the manager in this way is
+ to add the manager related config after starting the application (e.g
+ it cannot be part of the normal application config; sys.config).
+ This is done by calling:
+ <c>application:set_env(snmp, manager, Conf)</c>.
+ </p>
+ <p>The default value for <c>Type</c> is <c>normal</c>.</p>
+
+ <marker id="dat"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>date_and_time() -> DateAndTime</name>
+ <fsummary>Return the current date and time as an OCTET STRING</fsummary>
+ <type>
+ <v>DateAndTime = [int()]</v>
+ </type>
+ <desc>
+ <p>Returns current date and time as the data type DateAndTime,
+ as specified in RFC1903. This is an OCTET STRING.</p>
+
+ <marker id="dat2ut_dst"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>date_and_time_to_universal_time_dst(DateAndTime) -> [utc()]</name>
+ <fsummary>Convert a DateAndTime value to a list of possible utc()</fsummary>
+ <type>
+ <v>DateAndTime = [int()]</v>
+ <v>utc() = {{Y,Mo,D},{H,M,S}}</v>
+ </type>
+ <desc>
+ <p>Converts a DateAndTime list to a list of possible universal
+ time(s). The universal time value on the same format as defined in
+ calendar(3). </p>
+
+ <marker id="dat2s"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>date_and_time_to_string(DateAndTime) -> string()</name>
+ <name>date_and_time_to_string(DateAndTime, Validate) -> string()</name>
+ <fsummary>Convert a DateAndTime value to a string</fsummary>
+ <type>
+ <v>DateAndTime = [int()]</v>
+ <v>Validate = fun(Kind, Data) -> boolean()</v>
+ </type>
+ <desc>
+ <p>Converts a DateAndTime list to a printable string, according
+ to the DISPLAY-HINT definition in RFC2579.</p>
+
+ <p>The validation fun, <c>Validate</c>, allows for a more "flexible"
+ validation of the <c>DateAndTime</c> argument. Whenever the data
+ is found to not follow RFC2579, the fun is called to allow a more
+ "lax" validation.
+ See the <seealso marker="#vdat">validate_date_and_time/2</seealso>
+ function for more info on the <c>Validate</c> fun. </p>
+
+ <marker id="dat2s2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>date_and_time_to_string2(DateAndTime) -> string()</name>
+ <fsummary>Convert a DateAndTime value to a string</fsummary>
+ <type>
+ <v>DateAndTime = [int()]</v>
+ </type>
+ <desc>
+ <p>Converts a DateAndTime list to a printable string, according
+ to the DISPLAY-HINT definition in RFC2579, with the extension
+ that it also allows the values "hours from UTC" = 14 together with
+ "minutes from UTC" = 0. </p>
+
+ <marker id="lt2dat_dst"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>local_time_to_date_and_time_dst(Local) -> [DateAndTime]</name>
+ <fsummary>Convert a Local time value to a list of possible DateAndTime(s)</fsummary>
+ <type>
+ <v>Local = {{Y,Mo,D},{H,M,S}}</v>
+ <v>DateAndTime = [int()]</v>
+ </type>
+ <desc>
+ <p>Converts a local time value to a list of possible DateAndTime
+ list(s). The local time value on the same format as defined in
+ calendar(3).</p>
+
+ <marker id="ut2dat"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>universal_time_to_date_and_time(UTC) -> DateAndTime</name>
+ <fsummary>Convert a UTC value to DateAndTime</fsummary>
+ <type>
+ <v>UTC = {{Y,Mo,D},{H,M,S}}</v>
+ <v>DateAndTime = [int()]</v>
+ </type>
+ <desc>
+ <p>Converts a universal time value to a DateAndTime list. The
+ universal time value on the same format as defined in calendar(3).</p>
+
+ <marker id="vdat"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>validate_date_and_time(DateAndTime) -> bool()</name>
+ <name>validate_date_and_time(DateAndTime, Validate) -> bool()</name>
+ <fsummary>Check if a DateAndTime value is correct</fsummary>
+ <type>
+ <v>DateAndTime = term()</v>
+ <v>Validate = fun(Kind, Data) -> boolean()</v>
+ </type>
+ <desc>
+ <p>Checks if <c>DateAndTime</c> is a correct DateAndTime
+ value, as specified in RFC2579. This function can be used in
+ instrumentation functions to validate a DateAndTime value.</p>
+
+
+ <p>The validation fun, <c>Validate</c>, allows for a more "flexible"
+ validation of the <c>DateAndTime</c> argument. Whenever the data
+ is found to not follow RFC2579, the fun is called to allow a more
+ "lax" validation.
+ The input to the validation fun looks like this: </p>
+
+ <pre>
+ Kind Data
+ -------------- ----------------------
+ year {Year1, Year2}
+ month Month
+ day Day
+ hour Hour
+ minute Minute
+ seconds Seconds
+ deci_seconds DeciSeconds
+ diff [Sign, Hour, Minute]
+ valid_date {Year, Month, Day}
+ </pre>
+
+ <marker id="passwd2localized_key"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>passwd2localized_key(Alg, Passwd, EngineID) -> Key</name>
+ <fsummary>Generates an localized key</fsummary>
+ <type>
+ <v>Alg = algorithm()</v>
+ <v>algorithm() = md5 | sha</v>
+ <v>Passwd = string()</v>
+ <v>EngineID = string()</v>
+ <v>Key = list()</v>
+ </type>
+ <desc>
+ <p>Generates a key that can be used as an authentication
+ or privacy key using MD5 och SHA. The key is
+ localized for EngineID.</p>
+
+ <marker id="octet_string_to_bits"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>octet_string_to_bits(S) -> Val</name>
+ <fsummary>Convert an OCTET-STRING to BITS</fsummary>
+ <type>
+ <v>Val = bits()</v>
+ </type>
+ <desc>
+ <p>Utility function for converting a value of type
+ <c>OCTET-STRING</c> to <c>BITS</c>. </p>
+
+ <marker id="bits_to_octet_string"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>bits_to_octet_string(B) -> Val</name>
+ <fsummary>Convert an OCTET-STRING to BITS</fsummary>
+ <type>
+ <v>Val = octet_string()</v>
+ </type>
+ <desc>
+ <p>Utility function for converting a value of type <c>BITS</c>
+ to <c>OCTET-STRING</c>. </p>
+
+ <marker id="read_mib"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_mib(FileName) -> {ok, mib()} | {error, Reason}</name>
+ <fsummary></fsummary>
+ <type>
+ <v>FileName = string()</v>
+ <v>mib() = #mib{}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Read a compiled mib.</p>
+
+ <marker id="log_to_txt"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {error, Reason}</name>
+ <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start) -> ok | {error, Reason}</name>
+ <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok | {error, Reason}</name>
+ <fsummary>Convert an Audit Trail Log to text format</fsummary>
+ <type>
+ <v>LogDir = string()</v>
+ <v>Mibs = [MibName]</v>
+ <v>OutFile = string()</v>
+ <v>MibName = string()</v>
+ <v>LogName = string()</v>
+ <v>LogFile = string()</v>
+ <v>Start = Stop = null | datetime() | {local_time,datetime()} | {universal_time,datetime()} </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Converts an Audit Trail Log to a readable text file, where
+ each item has a trailing TAB character, and any TAB
+ character in the body of an item has been replaced by ESC
+ TAB.
+ </p>
+ <p>The function can be used on a running system, or by copying
+ the entire log directory and calling this function. SNMP
+ must be running in order to provide MIB information.
+ </p>
+ <p><c>LogDir</c> is the name of the directory where the audit
+ trail log is stored.
+ <c>Mibs</c> is a list of Mibs to be used. The function uses
+ the information in the Mibs to convert for example object
+ identifiers to their symbolic name.
+ <c>OutFile</c> is the name of the generated text-file.
+ <c>LogName</c> is the name of the log,
+ <c>LogFile</c> is the name of the log file.
+ <c>Start</c> is the start (first) date and time from which
+ log events will be converted and
+ <c>Stop</c> is the stop (last) date and time to which log
+ events will be converted.
+ </p>
+ <p>The format of an audit trail log text item is as follows:
+ </p>
+ <p><c>Tag Addr - Community [TimeStamp] Vsn</c><br></br>
+ <c>PDU</c></p>
+ <p>where <c>Tag</c> is <c>request</c>, <c>response</c>,
+ <c>report</c>, <c>trap</c> or <c>inform</c>; Addr is
+ <c>IP:Port</c> (or comma space separated list of such);
+ <c>Community</c> is the community parameter (SNMP version
+ v1 and v2), or <c>SecLevel:"AuthEngineID":"UserName"</c>
+ (SNMP v3); <c>TimeStamp</c> is a date and time stamp,
+ and <c>Vsn</c> is the SNMP version. <c>PDU</c> is a textual
+ version of the protocol data unit. There is a new line
+ between <c>Vsn</c> and <c>PDU</c>.</p>
+
+ <marker id="change_log_size"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>change_log_size(LogName, NewSize) -> ok | {error, Reason}</name>
+ <fsummary>Change the size of the Audit Trail Log</fsummary>
+ <type>
+ <v>LogName = string()</v>
+ <v>NewSize = {MaxBytes, MaxFiles}</v>
+ <v>MaxBytes = integer()</v>
+ <v>MaxFiles = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Changes the log size of the Audit Trail Log. The
+ application must be configured to use the audit trail log
+ function. Please refer to disk_log(3) in Kernel Reference
+ Manual for a description of how to change the log size.
+ </p>
+ <p>The change is permanent, as long as the log is not deleted.
+ That means, the log size is remembered across reboots.</p>
+
+ <marker id="print_version_info"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>print_version_info() -> void()</name>
+ <name>print_version_info(Prefix) -> void()</name>
+ <fsummary>Formatted print of result of the versions functions</fsummary>
+ <type>
+ <v>Prefix = string() | integer()</v>
+ </type>
+ <desc>
+ <p>Utility function(s) to produce a formatted printout of the versions
+ info generated by the <c>versions1</c> function</p>
+ <p>This is the same as doing, e.g.: </p>
+ <pre>
+ {ok, V} = snmp:versions1(),
+ snmp:print_versions(V).
+ </pre>
+
+ <marker id="versions1"></marker>
+ <marker id="versions2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>versions1() -> {ok, Info} | {error, Reason}</name>
+ <name>versions2() -> {ok, Info} | {error, Reason}</name>
+ <fsummary>Retrieve various system and application info</fsummary>
+ <type>
+ <v>Info = [info()]</v>
+ <v>info() = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Utility functions used to retrieve some system and
+ application info.</p>
+ <p>The difference between the two functions is in how they get
+ the modules to check. <c>versions1</c> uses the app-file and
+ <c>versions2</c> uses the function <c>application:get_key</c>.</p>
+
+ <marker id="print_versions"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>print_versions(VersionInfo) -> void()</name>
+ <name>print_versions(Prefix, VersionInfo) -> void()</name>
+ <fsummary>Formatted print of result of the versions functions</fsummary>
+ <type>
+ <v>VersionInfo = [version_info()]</v>
+ <v>version_info() = term()</v>
+ <v>Prefix = string() | integer()</v>
+ </type>
+ <desc>
+ <p>Utility function to produce a formatted printout of the versions
+ info generated by the <c>versions1</c> and <c>versions2</c>
+ functions</p>
+ <p>Example: </p>
+ <pre>
+ {ok, V} = snmp:versions1(),
+ snmp:print_versions(V).
+ </pre>
+
+ <marker id="enable_trace"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>enable_trace() -> void()</name>
+ <fsummary>Starts a tracer</fsummary>
+ <!--
+ <type>
+ <v>Prefix = string() | integer()</v>
+ </type>
+ -->
+ <desc>
+ <p>Starts a dbg tracer that prints trace events to stdout (using
+ plain io:format after a minor formatting). </p>
+
+ <marker id="disable_trace"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>disable_trace() -> void()</name>
+ <fsummary>Stop the tracer</fsummary>
+ <!--
+ <type>
+ <v>Prefix = string() | integer()</v>
+ </type>
+ -->
+ <desc>
+ <p>Stop the tracer. </p>
+
+ <marker id="set_trace1"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>set_trace(Targets) -> void()</name>
+ <fsummary>Set trace target</fsummary>
+ <type>
+ <v>Targets = target() | targets()</v>
+ <v>target() = module()</v>
+ <v>module() = atom()</v>
+ <v>targets() = [target() | {target(), target_options()}]</v>
+ <v>target_options() = [target_option()]</v>
+ <v>target_option() = {return_trace, boolean()} | {scope, scope()}</v>
+ <v>scope() = all_functions | exported_functions | function_name() | {function_name(), function_arity()}</v>
+ <v>function_name() = atom()</v>
+ <v>function_arity() = integer() >= 0</v>
+ </type>
+ <desc>
+ <p>This function is used to set up default trace on function(s)
+ for the given module or modules. The scope of the trace will be
+ all <em>exported</em> functions (both the call info and the return
+ value). Timestamp info will also be included. </p>
+
+ <marker id="reset_trace"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>reset_trace(Targets) -> void()</name>
+ <fsummary>Reset trace target</fsummary>
+ <type>
+ <v>Targets = module() | modules()</v>
+ <v>modules() = [module()]</v>
+ <v>module() = atom()</v>
+ </type>
+ <desc>
+ <p>This function is used to reset (disable) trace for the
+ given module(s). </p>
+
+ <marker id="set_trace2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>set_trace(Targets, Opts) -> void()</name>
+ <fsummary>Set trace target</fsummary>
+ <type>
+ <v>Targets = target() | targets()</v>
+ <v>target() = module()</v>
+ <v>module() = atom()</v>
+ <v>targets() = [target() | {target(), target_options()}]</v>
+ <v>target_options() = [target_option()]</v>
+ <v>target_option() = {return_trace, boolean()} | {scope, scope()}</v>
+ <v>scope() = all_functions | exported_functions | function_name() | {function_name(), function_arity()}</v>
+ <v>function_name() = atom()</v>
+ <v>function_arity() = integer() >= 0</v>
+ <v>Opts = disable | trace_options()</v>
+ <v>trace_options() = [trace_option()]</v>
+ <v>trace_option() = {timestamp, boolean()} | target_option()</v>
+ </type>
+ <desc>
+ <p>This function is used to set up trace on function(s) for the given
+ module or modules. </p>
+
+ <p>The example below sets up trace on the exported functions (default)
+ of module <c>snmp_generic</c> and all functions of module
+ <c>snmp_generic_mnesia</c>. With return values (which is default)
+ and timestamps in both cases (which is also default): </p>
+
+ <pre>
+ snmp:enable_trace(),
+ snmp:set_trace([snmp_generic,
+ {snmp_generic_mnesia, [{scope, all_functions}]}]),
+ .
+ .
+ .
+ snmp:set_trace(snmp_generic, disable),
+ .
+ .
+ .
+ snmp:disable_trace(),
+ </pre>
+
+ </desc>
+ </func>
+
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p>calendar(3)
+ </p>
+ </section>
+
+</erlref>
+