aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMicael Karlberg <[email protected]>2013-05-16 19:43:59 +0200
committerMicael Karlberg <[email protected]>2013-05-16 19:43:59 +0200
commit2d56595da89d9225d150912228cb158e80584f8e (patch)
tree972be5263da5df8611284cb0b546b1869401477d
parentaa4416d43316b1ac294b07ed4b5299adf7d7c6ad (diff)
downloadotp-2d56595da89d9225d150912228cb158e80584f8e.tar.gz
otp-2d56595da89d9225d150912228cb158e80584f8e.tar.bz2
otp-2d56595da89d9225d150912228cb158e80584f8e.zip
[snmp/agent] Updated documentation and release notes
-rw-r--r--lib/snmp/doc/src/notes.xml69
-rw-r--r--lib/snmp/doc/src/ref_man.xml1
-rw-r--r--lib/snmp/doc/src/snmp_app.xml27
-rw-r--r--lib/snmp/doc/src/snmp_config.xml31
-rw-r--r--lib/snmp/doc/src/snmpa_mib_data.xml232
5 files changed, 305 insertions, 55 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index b47d4237f5..2dfe347e42 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -34,6 +34,75 @@
<section>
+ <title>SNMP Development Toolkit 4.24</title>
+ <p>Version 4.24 supports code replacement in runtime from/to
+ version 4.23.1 and 4.23. </p>
+
+ <section>
+ <title>Improvements and new features</title>
+<!--
+ <p>-</p>
+-->
+
+ <list type="bulleted">
+ <item>
+ <p>[agent] Introduced a documented behaviour for the mib-server
+ <seealso marker="snmpa_mib_data">mib-data backend</seealso>.
+ At present only the default module (<c>snmpa_mib_data_tttn</c>) is
+ provided. </p>
+ <p>A config option for the (agent)
+ <seealso marker="snmp_config#agent_mib_server">mib-servers</seealso>
+ mib-data backend module has been added to the agent config options,
+ <seealso marker="snmp_config#agent_ms_data_module">data_module</seealso>. </p>
+ <p>Own Id: OTP-11101</p>
+ </item>
+ </list>
+
+ </section>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+<!--
+ <p>-</p>
+-->
+
+ <list type="bulleted">
+ <item>
+ <p>[compiler] Now handles MIBs importing the pesudotype BITS. </p>
+ <p>Own Id: OTP-10799</p>
+ </item>
+
+ <item>
+ <p>[compiler] The MIB compiler could not handle a table index
+ that was defined later in the MIB. </p>
+ <p>Own Id: OTP-10808</p>
+ </item>
+
+ </list>
+
+ </section>
+
+ <section>
+ <title>Incompatibilities</title>
+ <p>-</p>
+
+<!--
+ <list type="bulleted">
+ <item>
+ <p>[manager] The old Addr-and-Port based API functions, previously
+ long deprecated and marked for deletion in R16B, has now been
+ removed. </p>
+ <p>Own Id: OTP-10027</p>
+ </item>
+
+ </list>
+-->
+ </section>
+
+ </section> <!-- 4.23.1 -->
+
+
+ <section>
<title>SNMP Development Toolkit 4.23.1</title>
<p>Version 4.23.1 supports code replacement in runtime from/to
version 4.23. </p>
diff --git a/lib/snmp/doc/src/ref_man.xml b/lib/snmp/doc/src/ref_man.xml
index 92e8927f6d..2c12ac665a 100644
--- a/lib/snmp/doc/src/ref_man.xml
+++ b/lib/snmp/doc/src/ref_man.xml
@@ -44,6 +44,7 @@
<xi:include href="snmpa_error_io.xml"/>
<xi:include href="snmpa_error_logger.xml"/>
<xi:include href="snmpa_local_db.xml"/>
+ <xi:include href="snmpa_mib_data.xml"/>
<xi:include href="snmpa_mpd.xml"/>
<xi:include href="snmpa_network_interface.xml"/>
<xi:include href="snmpa_network_interface_filter.xml"/>
diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml
index 62dfa515d1..6ce5285a68 100644
--- a/lib/snmp/doc/src/snmp_app.xml
+++ b/lib/snmp/doc/src/snmp_app.xml
@@ -4,7 +4,7 @@
<appref>
<header>
<copyright>
- <year>1997</year><year>2012</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -340,7 +340,7 @@
<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()}</c></p>
+ <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>
@@ -365,7 +365,28 @@
<p>Default is <c>false</c>.</p>
</item>
- <marker id="agent_ms_cache"></marker>
+ <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>
diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml
index 42831ecb34..4e2e932b46 100644
--- a/lib/snmp/doc/src/snmp_config.xml
+++ b/lib/snmp/doc/src/snmp_config.xml
@@ -337,7 +337,7 @@
<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()} | {mob_data_mod, mib_data_mod()}</c></p>
+ <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>
@@ -362,28 +362,35 @@
<p>Default is <c>false</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_mib_data_mod"></marker>
- <tag><c><![CDATA[mib_data_mod() = snmpa_mib_data_tttn | snmpa_mib_data_ttln | module() <optional>]]></c></tag>
+ <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).
+ 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>
diff --git a/lib/snmp/doc/src/snmpa_mib_data.xml b/lib/snmp/doc/src/snmpa_mib_data.xml
index eeeb124d9d..8e79bb1673 100644
--- a/lib/snmp/doc/src/snmpa_mib_data.xml
+++ b/lib/snmp/doc/src/snmpa_mib_data.xml
@@ -23,10 +23,7 @@
<title>snmpa_mib_data</title>
<prepared></prepared>
- <responsible></responsible>
<docno></docno>
- <approved></approved>
- <checked></checked>
<date></date>
<rev></rev>
<file>snmpa_mib_data.xml</file>
@@ -41,76 +38,89 @@
must export the following functions: </p>
<list type="bulleted">
<item>
- <p>new/1</p>
+ <seealso marker="#new">new/1</seealso>
</item>
<item>
- <p>close/1</p>
+ <seealso marker="#close">close/1</seealso>
</item>
<item>
- <p>sync/1</p>
+ <seealso marker="#sync">sync/1</seealso>
</item>
<item>
- <p>load_mib/4</p>
+ <seealso marker="#load_mib">load_mib/4</seealso>
</item>
<item>
- <p>unload_mib/4</p>
+ <seealso marker="#unload_mib">unload_mib/4</seealso>
</item>
<item>
- <p>lookup/2</p>
+ <seealso marker="#lookup">lookup/2</seealso>
</item>
<item>
- <p>next/3</p>
+ <seealso marker="#next">next/3</seealso>
</item>
<item>
- <p>register_subagent/3</p>
+ <seealso marker="#register_subagent">register_subagent/3</seealso>
</item>
<item>
- <p>unregister_subagent/2</p>
+ <seealso marker="#unregister_subagent">unregister_subagent/2</seealso>
</item>
<item>
- <p>which_mib/2</p>
+ <seealso marker="#which_mib">which_mib/2</seealso>
</item>
<item>
- <p>which_mibs/1</p>
+ <seealso marker="#which_mibs">which_mibs/1</seealso>
</item>
<item>
- <p>whereis_mib/2</p>
+ <seealso marker="#whereis_mib">whereis_mib/2</seealso>
</item>
<item>
- <p>backup/2</p>
+ <seealso marker="#dump">dump/2</seealso>
</item>
<item>
- <p>dump/2</p>
+ <seealso marker="#info">info/1</seealso>
</item>
<item>
- <p>info/1,2</p>
+ <seealso marker="#backup">backup/2</seealso>
</item>
<item>
- <p>code_change/2</p>
+ <seealso marker="#code_change">code_change/4</seealso>
</item>
</list>
- <p>The semantics of them and their exact signatures are explained
- below. </p>
- <marker id="handle_error"></marker>
+ <p>The semantics of them and their exact signatures are
+ explained below. </p>
+
+ <p>Note that some of the data need to be "passed on" to the
+ symbolic-store for storage, see the default mib-server data
+ module, <c>snmpa_mib_data_tttn</c> for details. </p>
+
</description>
+
+ <section>
+ <title>CALLBACK FUNCTIONS</title>
+ <p>The following functions must be exported from a
+ <c>mib-server</c> data callback module: </p>
+
+ <marker id="new"></marker>
+ </section>
+
<funcs>
<func>
- <name>new(Storage) -> State</name>
- <fsummary>Create new (mib-storage) instance</fsummary>
+ <name>Module:new(Storage) -> State</name>
+ <fsummary>Create new (mib-server) data instance</fsummary>
<type>
<v>Storage = mib_storage()</v>
<v>State = term()</v>
</type>
<desc>
- <p>Create a new mib-storage instance. </p>
+ <p>Create a new mib-server data instance. </p>
<marker id="close"></marker>
</desc>
</func>
<func>
- <name>close(State) -> void()</name>
+ <name>Module:close(State) -> void()</name>
<fsummary>Close the mib-storage</fsummary>
<type>
<v>State = term()</v>
@@ -123,13 +133,13 @@
</func>
<func>
- <name>sync(State) -> void()</name>
+ <name>Module:sync(State) -> void()</name>
<fsummary>Synchronize to disc</fsummary>
<type>
<v>State = term()</v>
</type>
<desc>
- <p>Synchronize (write to disc, if possible) the data to disc.
+ <p>Synchronize (write to disc, if possible) the mib-server data.
This depends on the <c>mib_storage</c> option, and will only have
an effect if the mib-storage option has an actual disc component
(such as dets, or ets with a file). </p>
@@ -139,7 +149,7 @@
</func>
<func>
- <name>load_mib(State, Filename, MeOverride, TeOverride) -> {ok, NewState} | {error, Reason}</name>
+ <name>Module:load_mib(State, Filename, MeOverride, TeOverride) -> {ok, NewState} | {error, Reason}</name>
<fsummary>Load a mib into the mib-server</fsummary>
<type>
<v>State = NewState = term()</v>
@@ -160,7 +170,7 @@
</func>
<func>
- <name>unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}</name>
+ <name>Module:unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}</name>
<fsummary>Unload mib from the mib-server</fsummary>
<type>
<v>State = NewState = term()</v>
@@ -176,7 +186,7 @@
</func>
<func>
- <name>lookup(State, Oid) -> Reply</name>
+ <name>Module:lookup(State, Oid) -> Reply</name>
<fsummary>Find the mib-entry corresponding to the Oid</fsummary>
<type>
<v>State = term()</v>
@@ -187,19 +197,18 @@
<v>Reason = term()</v>
</type>
<desc>
- <p>Find the mib-entry corresponding to the Oid.
- If it is a variable, the Oid must be
- <Oid for var>.0
- and if it is a table, Oid must be
- <table>.<entry>.<col>.<any>.</p>
- <!-- FIX -->
+ <p>Find the mib-entry corresponding to the <c>Oid</c>.
+ If it is a variable, the <c>Oid</c> must be
+ &lt;Oid for var&gt;.0
+ and if it is a table, <c>Oid</c> must be
+ &lt;table&gt;.&lt;entry&gt;.&lt;col&gt;.&lt;any&gt;.</p>
<marker id="next"></marker>
</desc>
</func>
<func>
- <name>next(State, Oid, MibView) -> Reply</name>
+ <name>Module:next(State, Oid, MibView) -> Reply</name>
<fsummary>Finds the lexicographically next oid</fsummary>
<type>
<v>State = term()</v>
@@ -216,7 +225,7 @@
</func>
<func>
- <name>register_subagent(State, Oid, Pid) -> Reply</name>
+ <name>Module:register_subagent(State, Oid, Pid) -> Reply</name>
<fsummary>Register the subagent</fsummary>
<type>
<v>State = NewState = term()</v>
@@ -226,13 +235,156 @@
<v>Reason = term()</v>
</type>
<desc>
- <p>Register the the subagent, process,
+ <p>Register the subagent, process,
handling part of the mib-tree. </p>
<marker id="unregister_subagent"></marker>
</desc>
</func>
+ <func>
+ <name>Module:unregister_subagent(State, PidOrOid) -> Reply</name>
+ <fsummary>Unregister the subagent</fsummary>
+ <type>
+ <v>State = NewState = term()</v>
+ <v>Reply = {ok, NewState} | {ok, NewState, Pid} | {error, Reason}</v>
+ <v>PidOrOid = pid() | oid()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Unregister the subagent, handling part of the mib-tree,
+ as specified by the <c>oid()</c> or <c>pid()</c>
+ (<c>PidOrOid</c>). </p>
+ <p>When unregister the subagent using an <c>oid()</c>, the <c>pid()</c>
+ of the process handling the sub-tree is also returned. </p>
+
+ <marker id="dump"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:dump(State, Destination) -> Reply</name>
+ <fsummary>Unregister the subagent</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>Reply = ok | {error, Reason}</v>
+ <v>Destination = io | filename()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Dump the mib-server data to <c>stdio</c> (Destination = <c>io</c>) or
+ the specified file. </p>
+
+ <marker id="which_mib"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:which_mib(State, Oid) -> Reply</name>
+ <fsummary>Retrieve the mib file for an oid()</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>Reply = {ok, MibFile} | {error, Reason}</v>
+ <v>Oid = oid()</v>
+ <v>MibFile = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Retrieve the mib-file to which an given <c>oid()</c> belongs. </p>
+
+ <marker id="which_mibs"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:which_mibs(State) -> Reply</name>
+ <fsummary>Retrieve all loaded mib files</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>Reply = [{MibName, Filename}]</v>
+ <v>MibName = atom()</v>
+ <v>Filename = string()</v>
+ </type>
+ <desc>
+ <p>Retrieve all loaded mib-files. </p>
+
+ <marker id="whereis_mib"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:whereis_mib(State, MibName) -> Reply</name>
+ <fsummary>Retrieve the mib file for the mib</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>MibName = atom()</v>
+ <v>Reply = {ok, Filename} | {error, Reason}</v>
+ <v>Filename = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Retrieve the mib file for the mib. </p>
+
+ <marker id="info"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:info(State) -> Reply</name>
+ <fsummary>Retrieve misc info for the mib data</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>Reply = {ok, Filename} | {error, Reason}</v>
+ <v>Filename = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Retrieve misc info for the mib data. </p>
+ <p>This is a utility function used to inspect, for instance,
+ memory usage, in a simple way. </p>
+
+ <marker id="backup"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:backup(State, BackupDir) -> Reply</name>
+ <fsummary>Perform a backup of the mib-server data</fsummary>
+ <type>
+ <v>State = term()</v>
+ <v>Reply = ok | {error, Reason}</v>
+ <v>BackupDir = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Perform a backup of the mib-server data. </p>
+ <p>Note that its implementation dependant (and also
+ dependent on mib-storage is used) if a backup is possible. </p>
+
+ <marker id="code_change"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:code_change(Destination, Vsn, Extra, State) -> NewState</name>
+ <fsummary>Perform a code-change</fsummary>
+ <type>
+ <v>Destination = up | down</v>
+ <v>Vsn = term()</v>
+ <v>Extra = term()</v>
+ <v>State = NewState = term()</v>
+ </type>
+ <desc>
+ <p>Perform a code-change (upgrade or downgrade). </p>
+ <p>See
+ <seealso marker="gen_server">gen_server</seealso>
+ for more info regarding the <c>Vsn</c> and <c>Extra</c> arguments. </p>
+
+ </desc>
+ </func>
+
</funcs>
</erlref>