diff options
Diffstat (limited to 'lib/snmp/doc/src')
| -rw-r--r-- | lib/snmp/doc/src/notes.xml | 67 | ||||
| -rw-r--r-- | lib/snmp/doc/src/snmp_app.xml | 7 | ||||
| -rw-r--r-- | lib/snmp/doc/src/snmp_config.xml | 9 | ||||
| -rw-r--r-- | lib/snmp/doc/src/snmpm_user.xml | 187 |
4 files changed, 174 insertions, 96 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml index 1b954a5294..d213b67052 100644 --- a/lib/snmp/doc/src/notes.xml +++ b/lib/snmp/doc/src/notes.xml @@ -36,7 +36,7 @@ <section> <title>SNMP Development Toolkit 4.25</title> <p>Version 4.25 supports code replacement in runtime from/to - version 2.24.2, 4.24.1, 4.24, 4.23.1 and 4.23. </p> + version 4.24.2, 4.24.1, 4.24, 4.23.1 and 4.23. </p> <section> <title>Improvements and new features</title> @@ -46,11 +46,37 @@ <list type="bulleted"> <item> + <p>[agent] Enable SNMP to create missing database directories. </p> + <p>Add + <seealso marker="snmp_app#db_init_error"> + {db_init_error, create_db_and_dir}</seealso> option to SNMP + <seealso marker="snmp_app#manager_opts_and_types">manager</seealso> + and + <seealso marker="snmp_app#agent_opts_and_types">agent</seealso>. + This allows them to create any missing parent directories for + <c>db_dir</c>, rather than treating any missing directories + as a fatal error. + The default for <c>db_init_error</c>, which is <c>terminate</c>, + is unchanged. </p> + <p>Steve Vinoski</p> + <p>Own Id: OTP-11352</p> + </item> + + <item> + <p>[manager] Improved handling of unexpected return values from + <seealso marker="snmpm_user">snmpm_user</seealso> + callback functions. </p> + <p>Violations of the documented API (crashes or invalid return + values) will now result in an error message. </p> + <p>Own Id: OTP-11307</p> + </item> + + <item> <p>Add (atl) log conversion block option. </p> <p>It is now possible to request that the Audit Trail Log should be blocked during conversion (<c>log_to_txt</c> or <c>log_to_io</c>). - This could be usefull when coverting a large log (when there is - a chance it may otherwise wrap during conversion). </p> + This could be usefull when coverting an entire large log (when + there is a chance it may otherwise wrap during conversion). </p> <p>See agent <seealso marker="snmpa#log_to_txt">log_to_txt</seealso> and @@ -63,25 +89,46 @@ <p>Own Id: seq12433</p> </item> + <item> + <p>When converting an Audit Trail Log to text, a corrupt + log entry could cause the entire conversion to fail. </p> + <p>Also, for a log with sequence numbers, failing to + decode a log entry would cause the conversion to fail + (not because of the failed decode, but because of the + failure to write the error message). </p> + <p>Own Id: OTP-111453</p> + <p>Aux Id: Seq 12459</p> + </item> + </list> </section> <section> <title>Fixed Bugs and Malfunctions</title> +<!-- <p>-</p> +--> -<!-- <list type="bulleted"> <item> - <p>[agent] - see <seealso marker="snmpa#load_mibs">load_mibs</seealso> and - <seealso marker="snmpa#unload_mibs">unload_mibs</seealso>. </p> - <p>Own Id: OTP-11216</p> + <p>Wrong block cypher type used for AES ('aes_cbf128' + instead of 'aes_cfb128') when performing AES block + encrypt/decrypt which breaks SNMP usmAesCfb128Protocol + in agent and manager. </p> + <p>Own Id: OTP-11412</p> + </item> + + <item> + <p>[manager] When performing the AES encryption, invalid values for + the EngineBoots and EngineTime was used. </p> + <p>The values of the local agent was used, which would have produced + "some" values if an agent was actually running. + If not it would have caused a crash. </p> + <p>Own Id: OTP-11413</p> </item> </list> ---> </section> @@ -168,7 +215,7 @@ </list> --> </section> - + </section> <!-- 4.24.2 --> diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml index e5a05342c1..9ede75b943 100644 --- a/lib/snmp/doc/src/snmp_app.xml +++ b/lib/snmp/doc/src/snmp_app.xml @@ -763,12 +763,15 @@ </item> <marker id="db_init_error"></marker> - <tag><c>db_init_error() = terminate | create</c></tag> + <tag><c>db_init_error() = terminate | create | create_db_and_dir</c></tag> <item> <p>Defines what to do if the agent or manager 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> + agent/manager will remove the faulty file(s) and create new ones, + and <c>create_db_and_dir</c> means that the agent/manager will + create the database file along with any missing parent directories + for the database file.</p> <p>Default is <c>terminate</c>.</p> </item> diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml index 61ee7f00ee..30b46e6aa8 100644 --- a/lib/snmp/doc/src/snmp_config.xml +++ b/lib/snmp/doc/src/snmp_config.xml @@ -792,12 +792,15 @@ in so far as it will be converted to the new format if found. </item> <marker id="db_init_error"></marker> - <tag><c>db_init_error() = terminate | create</c></tag> + <tag><c>db_init_error() = terminate | create | create_db_and_dir</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> + agent/manager will terminate, <c>create</c> means that the + agent/manager will remove the faulty file(s) and create new ones, + and <c>create_db_and_dir</c> means that the agent/manager will + create the database file along with any missing parent directories + for the database file.</p> <p>Default is <c>terminate</c>.</p> </item> diff --git a/lib/snmp/doc/src/snmpm_user.xml b/lib/snmp/doc/src/snmpm_user.xml index 1823e0c815..cb2deab976 100644 --- a/lib/snmp/doc/src/snmpm_user.xml +++ b/lib/snmp/doc/src/snmpm_user.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -56,40 +56,59 @@ <item> <p>handle_report/3</p> </item> + <item> + <p>handle_invalid_result/2</p> + </item> </list> <p>The semantics of them and their exact signatures are explained - below. </p> - <p>Note that if an agent is registered using the old, no longer - documented, functions (using Addr and Port), the old variant of the - callback functions, handle_pdu, handle_trap, handle_inform and - handle_report, will be called. </p> + below. </p> + <p>Some of the function has no defined return value (<c>void()</c>), + they can ofcourse return anythyng. But the functions that do have + specified return value(s) <em>must</em> adhere to this. None of the + functions can use exit of throw to return. </p> - <marker id="handle_error"></marker> + <marker id="types"></marker> </description> + + <section> + <title>DATA TYPES</title> + <code type="none"><![CDATA[ +snmp_gen_info() = {ErrorStatus :: atom(), + ErrorIndex :: pos_integer(), + Varbinds :: [snmp:varbind()]} +snmp_v1_trap_info() :: {Enteprise :: snmp:oid(), + Generic :: integer(), + Spec :: integer(), + Timestamp :: integer(), + Varbinds :: [snmp:varbind()]} + ]]></code> + <marker id="handle_error"></marker> + </section> + <funcs> <func> - <name>handle_error(ReqId, Reason, UserData) -> Reply</name> + <name>handle_error(ReqId, Reason, UserData) -> void()</name> <fsummary>Handle error</fsummary> <type> <v>ReqId = integer()</v> <v>Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info, SecInfo, SnmpInfo} | {empty_message, Addr, Port} | term()</v> + <v>SnmpInfo = snmp_gen_info()</v> + <v>SecInfo = term()</v> <v>Addr = ip_address()</v> <v>Port = integer()</v> <v>UserData = term()</v> - <v>Reply = ignore</v> </type> <desc> <p>This function is called when the manager needs to - communicate an "asynchronous" error, to the user: - e.g. failure to send an asynchronous message (i.e. encoding - error), a received message was discarded due to security - error, the manager failed to generate a response message to - a received inform-request, or when receiving an unexpected - PDU from an agent (could be an expired async request). </p> - <p>If <c>ReqId</c> is less then 0, it means that this - information was not available to the manager (that info was - never retrieved before the message was discarded). - </p> + communicate an "asynchronous" error to the user: + e.g. failure to send an asynchronous message (i.e. encoding + error), a received message was discarded due to security + error, the manager failed to generate a response message to + a received inform-request, or when receiving an unexpected + PDU from an agent (could be an expired async request). </p> + <p>If <c>ReqId</c> is less then 0, it means that this + information was not available to the manager (that info was + never retrieved before the message was discarded). </p> <p>For <c>SnmpInfo</c> see handle_agent below.</p> <marker id="handle_agent"></marker> @@ -104,22 +123,22 @@ <v>Port = integer()</v> <v>Type = pdu | trap | report | inform</v> <v>SnmpInfo = SnmpPduInfo | SnmpTrapInfo | SnmpReportInfo | SnmpInformInfo</v> - <v>ErrorStatus = atom()</v> - <v>ErrorIndex = integer()</v> - <v>Varbinds = [varbind()]</v> - <v>varbind() = #varbind</v> + <v>SnmpPduInfo = snmp_gen_info()</v> + <v>SnmpTrapInfo = snmp_v1_trap_info()</v> + <v>SnmpReportInfo = snmp_gen_info()</v> + <v>SnmpInformInfo = snmp_gen_info()</v> <v>UserData = term()</v> - <v>Reply = ignore | {register, UserId, TargetName, agent_info()}</v> + <v>Reply = ignore | {register, UserId, TargetName, AgentConfig}</v> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v> + <v>AgentConfig = [agent_config()]</v> </type> <desc> - <p>This function is called when a message is received from an - unknown agent.</p> + <p>This function is called when a message is received from an + unknown agent.</p> <p>Note that this will always be the default user that is called.</p> - <p>For more info about the <c>agent_info()</c>, see - <seealso marker="snmpm#register_agent">register_agent</seealso>.</p> + <p>For more info about the <c>agent_config()</c>, see + <seealso marker="snmpm#register_agent">register_agent</seealso>.</p> <p>The arguments <c>Type</c> and <c>SnmpInfo</c> relates in the following way: </p> @@ -148,7 +167,7 @@ </list> <p>The only user which would return - <c>{register, UserId, TargetName, agent_info()}</c> is the + <c>{register, UserId, TargetName, AgentConfig}</c> is the <em>default user</em>.</p> <marker id="handle_pdu"></marker> @@ -156,18 +175,13 @@ </func> <func> - <name>handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> Reply</name> + <name>handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> void()</name> <fsummary>Handle the reply to an asynchronous request</fsummary> <type> <v>TargetName = target_name()</v> <v>ReqId = term()</v> - <v>SnmpPduInfo = {ErrorStatus, ErrorIndex, Varbinds}</v> - <v>ErrorStatus = atom()</v> - <v>ErrorIndex = integer()</v> - <v>Varbinds = [varbind()]</v> - <v>varbind() = #varbind</v> + <v>SnmpPduInfo = snmp_gen_info()</v> <v>UserData = term()</v> - <v>Reply = ignore</v> </type> <desc> <p>Handle the reply to an asynchronous request, such as @@ -186,27 +200,19 @@ <fsummary>Handle a trap/notification message</fsummary> <type> <v>TargetName = TargetName2 = target_name()</v> - <v>SnmpTrapInfo = {Enteprise, Generic, Spec, Timestamp, Varbinds} | {ErrorStatus, ErrorIndex, Varbinds}</v> - <v>Enterprise = oid()</v> - <v>Generic = integer()</v> - <v>Spec = integer()</v> - <v>Timestamp = integer()</v> - <v>ErrorStatus = atom()</v> - <v>ErrorIndex = integer()</v> - <v>Varbinds = [varbind()]</v> - <v>varbind() = #varbind</v> + <v>SnmpTrapInfo = snmp_v1_trap_info() | snmp_gen_info()</v> <v>UserData = term()</v> - <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v> + <v>Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}</v> <v>UserId = term()</v> - <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v> + <v>AgentConfig = [agent_config()]</v> </type> <desc> <p>Handle a trap/notification message from an agent.</p> - <p>For more info about the <c>agent_info()</c>, see - <seealso marker="snmpm#register_agent">register_agent</seealso></p> + <p>For more info about the <c>agent_config()</c>, see + <seealso marker="snmpm#register_agent">register_agent</seealso></p> <p>The only user which would return - <c>{register, UserId, TargetName2, agent_info()}</c> is the - <em>default user</em>.</p> + <c>{register, UserId, TargetName2, agent_info()}</c> is the + <em>default user</em>.</p> <marker id="handle_inform"></marker> </desc> @@ -217,29 +223,25 @@ <fsummary>Handle a inform message</fsummary> <type> <v>TargetName = TargetName2 = target_name()</v> - <v>SnmpInformInfo = {ErrorStatus, ErrorIndex, Varbinds}</v> - <v>ErrorStatus = atom()</v> - <v>ErrorIndex = integer()</v> - <v>Varbinds = [varbind()]</v> - <v>varbind() = #varbind</v> + <v>SnmpInformInfo = snmp_gen_info()</v> <v>UserData = term()</v> - <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v> + <v>Reply = ignore | no_reply | unregister | {register, UserId, TargetName2, AgentConfig}</v> <v>UserId = term()</v> - <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v> + <v>AgentConfig = [agent_config()]</v> </type> <desc> <p>Handle a inform message.</p> - <p>For more info about the <c>agent_info()</c>, see - <seealso marker="snmpm#register_agent">register_agent</seealso></p> + <p>For more info about the <c>agent_config()</c>, see + <seealso marker="snmpm#register_agent">register_agent</seealso></p> <p>The only user which would return - <c>{register, UserId, TargetName2, agent_info()}</c> is the - <em>default user</em>.</p> - <p>If the - <seealso marker="snmp_app">inform request behaviour</seealso> - configuration option is set to <c>user</c> or - <c>{user, integer()}</c>, the response (acknowledgment) to this - inform-request will be sent when this function returns.</p> - + <c>{register, UserId, TargetName2, AgentConfig}</c> is the + <em>default user</em>.</p> + <p>If the + <seealso marker="snmp_app">inform request behaviour</seealso> + configuration option is set to <c>user</c> or + <c>{user, integer()}</c>, the response (acknowledgment) to this + inform-request will be sent when this function returns.</p> + <marker id="handle_report"></marker> </desc> </func> @@ -251,23 +253,46 @@ <v>TargetName = TargetName2 = target_name()</v> <v>Addr = ip_address()</v> <v>Port = integer()</v> - <v>SnmpReportInfo = {ErrorStatus, ErrorIndex, Varbinds}</v> - <v>ErrorStatus = atom()</v> - <v>ErrorIndex = integer()</v> - <v>Varbinds = [varbind()]</v> - <v>varbind() = #varbind</v> + <v>SnmpReportInfo = snmp_gen_info()</v> <v>UserData = term()</v> - <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v> + <v>Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}</v> <v>UserId = term()</v> - <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v> + <v>AgentConfig = [agent_config()]</v> </type> <desc> <p>Handle a report message.</p> - <p>For more info about the <c>agent_info()</c>, see - <seealso marker="snmpm#register_agent">register_agent</seealso></p> + <p>For more info about the <c>agent_config()</c>, see + <seealso marker="snmpm#register_agent">register_agent</seealso></p> <p>The only user which would return - <c>{register, UserId, TargetName2, agent_info()}</c> is the - <em>default user</em>.</p> + <c>{register, UserId, TargetName2, AgentConfig}</c> is the + <em>default user</em>.</p> + + <marker id="handle_invalid_result"></marker> + </desc> + </func> + + <func> + <name>handle_invalid_result(IN, OUT) -> void()</name> + <fsummary>Handle a report message</fsummary> + <type> + <v>IN = {Func, Args}</v> + <v>Func = atom()</v> + <v>Args = list()</v> + <v>OUT = {crash, CrashInfo} | {result, InvalidResult}</v> + <v>CrashInfo = {ErrorType, Error, Stacktrace}</v> + <v>ErrorType = atom()</v> + <v>Error = term()</v> + <v>Stacktrace = list()</v> + <v>InvalidResult = term()</v> + </type> + <desc> + <p>If <em>any</em> of the <em>other</em> callback functions crashes + (exit, throw or a plain crash) or return an invalid result (if a valid + return has been specified), this function is called. + The purpose is to allow the user handle this + error (for instance to issue an error report).</p> + <p><c>IN</c> reprecents the function called (and its arguments). + <c>OUT</c> represents the unexpected/invalid result. </p> </desc> </func> </funcs> |