Home

Simple Network Management Protocol (SNMP)

1. a er o o E e o aa a T 48 1 8 6 Security data for USM o o o 4 48 18 7 Trap Destinations ii 2 a4 aclu AA seas ea a a 49 1 8 8 Notify Definitions aoaaa aa 49 1 8 9 Target AddressDefinitions 2 00 ce ee 49 1 8 10 Target ParametersDefinitions aooaa e 50 Definition of Instrumentation Functions 1 0 0 00 cee eee 50 1 9 1 Variable Instrumentation oaoa 50 1 9 2 Table Instrumentation o e 52 Definition of Net if ansi e S44 aa GE i Boe ete doy eat a A Mo Pee 55 1 10 1 Mandatory FUNCtIONS a aer a a a a E e 56 TIO Z AMES o ir e e e A AA de ak Be ded 56 SNM PA ppendix A iiri com AAA A A a 58 VITEL AppPENAIX Ar arini ia ou ee Ba ES A a 58 SNMP Appendix Bon gees dd a ee ee eee ao eee ee RS 59 1 12 LA PPeNndIX Birri ae fete ee Faded fae a dee Be BS 59 SNMP Release Notes onua aaa ee 68 1 13 1 SNMP Development Toolkit v3 3 8 a aaa o e 68 1 13 2 SNMP Development Toolkit v3 3 7 aaa oo ee 68 Simple N etwork M anagement Protocol SN M P 1 13 3 SNMP Development Toolkit v3 3 6 0 o e 69 1 13 4 SNMP Development Toolkit v3 3 5 0 o o e 69 1 13 5 SNMP Development Toolkit v3 3 4 0 0 o o eee 70 1 13 6 SNMP Development Toolkit v3 3 3 o o o 70 1 13 7 SNMP Development Toolkit v3 3 2 oo oo 70 1 13 8 SNMP Development Toolkit v3
2. An Oid is represented as a list For convenience nested lists are allowed There is one exception though If an oid is entered in symbolic form this symbol must be the first item in the list A symbolic name includes the complete path from the top of the global naming tree Accordingly an oid can only contain one symbolic name Examples of valid O ids are myVar 0 1 2 3 4 5 0 myColumn 95 myTable 4 123 5 eklas The last example refers to column 4 of the row with the two keys 123 and 5 eklas of table myTable Known bug There is not yet a timeout M secs option Simple N etwork M anagement Protocol SN M P 129 snmp_mgr expect Id expect Id expect Id expect Id expect Id expect Id SNMP Reference Manual Exports What gt ok error Id Reason ErrorStatus ErrorIndex Varbinds trap Enterp Generic Specific Varbinds v2trap Varbinds report Varbinds inform InformReply Varbinds Types e Id term e What any trap timeout Varbinds ErrorStatus e Errorlndex integer e Enterp oid e Generic integer e Specific integer e InformReply true false error ErrorStatus Errorlndex Id is used to help identifying this particular test in a long test suite It is not used by the manager e The atom any makes the test succeed for any response timeout succeeds if the message queue is empty for 3 5 seconds This can be used to ensure that no messages a
3. Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions DEFVALs for strings are handled correctly by the Mib Compiler The SN MPv2 error code notWritable is translated to the SN M Pv1 code noSuchName The instrumentation function delete is now called correctly when unloading a Mib An is_set_ok function is added for snmp_generic variable func snmp mib_to_hr1 doesn t generate output for imported M IB objects The SNMP type IpAddress is now BER encoded correctly The agent could hang when last object in the MIB was not accessible and a GET NEXT request was received The Mib Compiler doesn t crash when the M IB file doesn t exist The Mib Compiler doesn t crash when an instrumentation function is specified for a column object in a table Incompatibilities with v1 1 The M IBs must be recompiled The contents of the output file from snmp mib_to_hr1 has changed Imported objects are not included All MIBs with imported objects must be run through snmp mib_to_hr1 and included in the Erlang code as well The start functions for the agent has changed Note that this is invisible when Erlang 4 4 is used Simple N etwork M anagement Protocol SN M P 87 Chapter 1 SNMP User s Guide 88 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual Short Summaries Application snmp page 99 The SNMP Application Erlang M odule snmp page 101 Interface Function
4. the following two values are states these values may be read or written active 1 notInService 2 the following value is a state this value may be read but not written notReady 3 Simple N etwork M anagement Protocol SN M P 67 Chapter 1 SNMP User s Guide the following three values are actions these values may be written oS but are never read createAndGo 4 createAndWait 5 destroy 6 1 13 SNMP Release Notes 1 13 1 SNMP Development Toolkit v3 3 8 Version 3 3 8 supports code replacement in runtime from to version 3 3 7 3 3 6 and 3 3 5 Improvements and new features e Incase the UDP port dies the snmp _net_if process now reports this and also tries to re open the port Own Id OTP 4457 Aux Id Seq 7594 e SNMP mib compiler warning s cleanup Some of the warnings eg about missing accessfunction was changed into info printouts which can be seen with the compiler erlc argument verbosity info See SNM P compiler options page 101 Own Id OTP 4478 Reported Fixed Bugs and Malfunctions e The agent side set and is_set_ok operations on the snmpTargetA ddrE xtTable was incorrect Own Id OTP 4477 Aux Id Seq 7444 1 13 2 SNMP Development Toolkit v3 3 7 Version 3 3 7 supports code replacement in runtime from to version 3 3 6 3 3 5 3 3 4 3 3 3 and 3 3 2 Improvements and new features Reported Fixed Bugs and Malfunctions e SNMP Target mib tag check incorrect
5. Standard MIB Network Figure 1 3 Architecture A typical operation could include the following steps 1 The M anager sends a request to the A gent 2 The Master A gent decodes the incoming U DP packet 3 The Master Agent determines which items in the request that should be processed here and which items should be forwarded to its subagent Step 3 is repeated by all subagents Each subagent calls the instrumentation for its loaded M IBs The results of calling the instrumentation are propagated back to the M aster Agent The answer to the request is encoded to aUDP Protocol Data Unit PDU Y O Ul a Simple N etwork M anagement Protocol SN M P 7 Chapter 1 SNMP User s Guide The sequence of steps shown is probably more complex than normal but it illustrates the amount of functionality which is available The following points should be noted e An agent can have many M IBs loaded at the same time e Subagents can also have subagents Each subagent can have an arbitrary number of child subagents registered forming a hierarchy e One MIB can communicate with many applications e Instrumentation can use Distributed Erlang to communicate with an application M ost applications only need the M aster A gent because an agent can have multiple M IBs loaded at the same time 1 25 Subagents and MIB Loading Since applications tend to be transient they are dynamically loaded and unloaded the management of these
6. The option warnings specifies whether warning messages should be shown Default is true The option verbosity specifies the verbosity of the SN MP mib compiler l e if warning info log debug and trace messages shall be shown Default is silence N ote that if the option warnings is true and the option verbosity iS silence warning messages will still be shown The option group_check specifies whether the mib compiler should check the OBJECT GROUP macro for correctness or not Default is true The option deprecated specifies if a deprecated definition should be ignored or not If the option is true will the MIB compilator ignore all deprecated definitions D efault is false The option description specifies if the text of the DESCRIPTION field will be included or not Default is false in which case the description will be replaced by the atom undefined The MIB compiler understands both SM Iv1 and SM Iv2 MIBs It uses the MODULE IDENTITY statement to determine if the MIB is version 1 or 2 The MIB compiler can be invoked from the OS command line by using the command erlc erlc recognises the extension mib and invokes the SN MP MIB compiler for files with that extension The options db group_check and deprecated have to be specified to erlc using the syntax term See er1c 1 for details change_log_size NewSize gt ok error Reason Types e NewSize M axBytes M axFiles e MaxBytes integer e MaxFiles intege
7. friendsEntry 2 fAddress OBJECT TYPE SYNTAX DisplayString SIZE 0 255 ACCESS read write STATUS mandatory DESCRIPTION Address of friend friendsEntry 3 gt fStatus OBJECT TYPE SYNTAX RowStatus ACCESS read write STATUS mandatory DESCRIPTION The status of this conceptual row friendsEntry 4 fTrap TRAP TYPE ENTERPRISE examplel VARIABLES myName fIndex DESCRIPTION This trap is sent when something happens to the friend specified by flIndex wel END 1 6 2 Default Implementation Without writing any instrumentation functions we can compile the MIB and use the default implementation of it Recall that MIBs imported by EX 1 MIB mib must be present and compiled in the current directory STANDARD MIB bin RFC1213 M IB bin when compiling unix gt erl config sys 1 gt application start snmp 32 Simple N etwork M anagement Protocol SN M P 1 6 Implementation Example ok 2 gt snmp c EX1 MIB No accessfunction for friendsTable using default No accessfunction for myName using default ok EX1 MIB bin 3 gt snmp loadmibs snmpmaster_agent EX1 MIB ok This MIB is now loaded into the agent and a manager can ask questions As an example of this we start another Erlang system and the simple Erlang manager in the toolkit 1 gt snmpmgr start_link agent dront ericsson se community all rights ok lt 0 89 0 gt hh a get next
8. gt ok Packet discarded 134 Reason Types e Vsn version 1 version 2 version 3 e RePdu odu Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_mpd e Type atom e ACM Data acm _data e Packet binary Generates a possibly encrypted response packet to be sent to the network Type is the pdu type of the original request generate msg Vsn Pdu MsgData To gt ok PacketsAndAddresses discarded Reason Types e Vsn version 1 version 2 version 3 e Pdu odu e MsgD ata msg_data e To dest_addrs e PacketsA ndA ddresses TD omain TA ddress Packet e TDomain snmpU DPD omain e TAddress Ip Udp e Ip integer integer integer integer e Udp integer e Packet binary Generates a possibly encrypted request packet to be sent to the network MsgData is the message specific data used in the SN MP message This value is received in a send_pdu or send_pdu_req message from the agent In SNM Pv1 and SN MPv2c this message data is the community string In SN M Pv3 it is the context information To isa list of the destination addresses and their corresponding security parameters This value is also received from the requests mentioned above discarded_pdu Variable gt void Types e Variable atom Increments the variable associated with a discarded pdu This function can be used when the net_if process rec
9. If it is possible for a manager to create or delete rowsin the table there must bea RowStatus column for is_set_ok set and undo to work properly The function returns according to the specification of an instrumentation function table_get_elements NameDb RowIndex Cols gt Values Types e Values term noinit Returns a list with values for all columns in Cols If a column is undefined its value is noinit table_next NameDb RestOid gt RowIndex endOfTable Types e RestO id int Finds the indices of the next row in the table RestOid does not have to specify an existing row table_row_exists NameDb RowIndex gt bool Checks if a row in atable exists table_set_elements NameDb RowIndex Cols gt bool Sets the elements in Cols to the row specified by RowIndex No checks are performed on the new values If the M nesia database is used this function calls mmesia write to store the values This means that this function must be called from within a transaction mnesia transaction 1 Or mnesia dirty 1 variable_func Op1 NameDb variable func 0p2 Val NameDb gt Ret Types e Opl new delete get e Op2 is_set_ok set undo This is the default instrumentation function for variables The new function creates a new variable in the database with a default value as defined in the MIB or azero value depending on the type The delete function does not delete the variable from the database The f
10. Valid return values e noError e badValue noSuchName genErr SNM Pv1 e noAccess noCreation inconsistentValue resourceUnavailable inconsistentName genErr SNM Pv2 f undo NewValue ExtraArgs If an error occurred this function is called after the is_set_ok function is called If set is called for this object undo is not called NewValue is guaranteed to be of the correct type length and within ranges as specified in the MIB If the object is an enumerated integer or of type BITS the integer value is used This function is optional Valid return values e noError e genErr SNMPvl e undoFailed genErr SN M Pv2 Simple N etwork M anagement Protocol SN M P 51 Chapter 1 SNMP User s Guide f set NewValue ExtraArgs This function is called to perform the set in phase two of the set request processing It is only called if the corresponding is_set_ok function is present and returns noError NewValue is guaranteed to be of the correct type length and within ranges as specified in the M IB If the object is an enumerated integer or of type BITS the integer value is used This function is mandatory Valid return values e noError e genErr SNMPvl e commitFailed undoFailed genErr SN M Pv2 1 9 2 Table Instrumentation For tables a f Operation function should be defined the function shown is exemplified with The Operation Can be new delete get next is_set_ok undo Or
11. If false and some errors occur anew datebase is created instead If true erroneous transactions in the logfile are ignored If true_verbose erroneous transactions in the logfile are igored and an error message is written Default is true snmp mibentry_override bool lt optional gt If this value is false then when loading a mib each mib entry is checked prior to installation of the mib The perpose of the check is to prevent that the same symbolic mibentry name is used for different oid s D efault is false snmp_trapentry_override bool lt optional gt If this value is false then when loading a mib each trap is checked prior to installation of the mib The perpose of the check is to prevent that the same symbolic trap name is used for different trap s Default is false snmp_error_report mod atom lt optional gt Defines an error report module other then the default Two modules are provided with the toolkit snmp_error and snmp_error_io Default is snmp_error snmp_master_agent_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SN MP master agent Default is silence snmp_symbolic_store_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP symbolic store Default is silence snmp_note_store_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP no
12. Own Id OTP 4394 Aux Id Seq 7444 68 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes 1 13 3 SNMP Development Toolkit v3 3 6 Version 3 3 6 supports code replacement in runtime from to version 3 3 5 3 3 4 3 3 3 and 3 3 2 Improvements and new features Reported Fixed Bugs and Malfunctions e Improved error handling in snmp_error_report module ets lookup failure Own Id OTP 4345 Aux Id Seg 7309 e SNMP NotifiyType error Calls to the functions snmp_notificationmib get_targets 0 failes since it assumes that notify type was stored as atoms which is not always the case Furthermore the parsing of the notify config file did not convert the trap and inform to their respective integer values 1 and 2 Own Id OTP 4329 Aux Id Seq 7367 1 13 4 SNMP Development Toolkit v3 3 5 Version 3 3 5 supports code replacement in runtime from to version 3 3 4 3 3 3 and 3 3 2 Improvements and new features e When opening a log file the failure reason was not checked Instead it was assumed to be badarg size when opened without the size option this means the file does not exist This is usually correct but just to be on the safe side the test has beem changed to make sure that no other results get through Own Id OT P 4282 Aux Id Seq 7312 Added possiblillity to specify own error report module instead of the default snmp_error This is done with a new application config directive snmp_error_report
13. delete_row RowIndex gt NewTable table_delete_row Table RowIndex loop MyName NewTable From fadd_row NewRow gt NewTable table_add_row Table NewRow loop MyName NewTable end IN hhh Functions for table operations The table is represented as ahh a list of rows Doha IT table_get_row Index Name Address Status _ Index gt ok Index Name Address Status table_get_row H T RowIndex gt table_get_row T RowIndex table_get_row _RowIndex gt no_such_row table_get_next_row Row T gt lok Row table_get_next_row Row T Index _ when element 1 Row gt Index gt lok Row table_get_next_row Row T RowIndex gt table_get_next_row T RowIndex table_get_next_row RowIndex gt endOfTable table_delete_row Index _ _ _ T Index gt T table_delete_row H T RowIndex gt H table_delete_row T RowIndex Simple N etwork M anagement Protocol SN M P 37 Chapter 1 SNMP User s Guide table_delete_row _RowIndex gt table_add_row Row T NewRow when element 1 Row gt element 1 NewRow gt NewRow Row T table_add_row H T NewRow gt H table_add_row T NewRow table_add_row NewRow gt NewRow make_row Index 2 Name 3 Address _ gt Index Name Address active merge_rows Row Col NewVal T gt merge_rows setelement Col R
14. modes of operation First it can be used as a simple command line manager Second it can be used to write test suites for testing the MIB implementation in the SNMP agent The manager supports SN M Pv1 SN M Pv2c and SNM Pv3 including authentication and privacy The command line manager uses the Erlang shell It supports all SNM Pv1 v2 and v3 requests i e set get get next and get bulk For example samp mgr s 1 2 3 0 hej sends a set request to the agent and snmp mgr g 1 2 3 0 myVar 0 gets two values The manager operates asynchronously This implies that the return value of most functions is nonsense W hen the manager gets a response message from the agent it is echoed to the display The start up option quiet tells the manager not to display incoming SN MP responses traps and informs M essages are sent to the Erlang process that started the manager This makes it possible to process them from an application or a test suite Use the expect function that operates on the message queue to write test suites Examples of how to write a test suite can be found in snmp_mgr_tests erl M IBs M anagement Information Base can be loaded in the manager There are two reasons for doing this OBJECT IDENTIFIERs O ids can be entered in symbolic form Example instead of 1 3 6 1 2 1 1 1 the symbolic name sysDescr can be used The other reason is to take advantage of the type information in the MIB when sending set requests
15. or snmpnotification Tag no_response ManagerAddr for each management target Sometimes it is not possible to retrieve the values for some of the objects in the notification specification with a get operation H owever they are known when the send_notification function is called This is the case if an object is an element in a table It is possible to give the values of some objects to the send_notification function snmp sendnotification Agent Notification Receiver Varbinds In this function Varbinds is a list of Varbind where each Varbind is one of e Variable Value where Variable is the symbolic name of a scalar variable referred to in the notification specification e Column RowIndex Value where Column is the symbolic name of a column variable RowIndex is a list of indices for the specified element If this is the case the O BJ ECT IDENTIFIER sent in the trap is the RowIndex appended to the OBJECT IDENTIFIER for the table column This isthe OBJECT IDENTIFIER which specifies the element e 0ID Value where OID isthe OBJECT IDENTIFIER for an instance of an object scalar variable or column variable Simple N etwork M anagement Protocol SN M P 15 Chapter 1 SNMP User s Guide For example to specify that sysLocation should have the value upstairs in the notification we could use one of e sysLocation upstairs or e 1 3 6 1 2 1 1 6 0 upstairs It is also possible to specify names and values fo
16. snmp enum_to_int 2 and snmp int_to_enum 2 works for types as well as for objects RowStatus no longer needs to be the last column for snmp_generic to work This allows a table to be extended at a later stage A table doesn t need to have all columns defined Example snmp_generic can handle a table with columns 1 2 3 5 snmp_generic works even though some columns in the middle of a table are not accessible Default values for strings may use syntax The Mib Compiler understands both SN M Pv1 and SN M Pv2 MIBs and implements cross version IM PORTS The Mib Compiler produces several error messages at the same time The Mib Compiler is more strict snmp_mgr can send and receive SN M Pv2 messages snmp conf ig 0 generates a sys config file Added a record definition for the M nesia table snmp_variables to snmp_types hrl The master agent may now be a distributed Erlang applications and it reloads loaded mib during takeover Reported Fixed Bugs and Malfunctions The Mib Compiler and snmp_generic handle objects with STATUS deprecated and obsolete Own Id OTP 1372 Aux Id HA47707 Agent restarts after crashes keeps information about loaded mibs Previously the agent restarted but all loaded mibs were unloaded Own Id OTP 1423 Aux Id AD84262 Simple N etwork M anagement Protocol SN M P 83 Chapter 1 SNMP User s Guide e The generated hr1 files now starts with an ifndef which makes it possible to include the s
17. this file is automatically converted to the new files and these new files are read 1 8 8 Notify Definitions The information about Notify D efinitions should be stored in a file called notify conf The corresponding table is snmpNotifyTable in the SNMP NOTIFICATION MIB Each entry is a term NotifyName Tag Type e NotifyName is a unique non empty string e Tag isa string e Type iS trap Or inform 1 8 9 Target Address Definitions The information about Target Address D efinitions should be stored in a file called target_addr conf The corresponding tables are snmpTargetAddrTable in the SN MP TARGET MIB and snmpTargetAddrExtTable in the SNMP COMMUNITY MIB Each entry is a term TargetName Ip Udp Timeout RetryCount TagList ParamsName or TargetName Ip Udp Timeout RetryCount TagList ParamsName TMask MaxMessageSize TargetName is a unique non empty string Ip is alist of four integers Udp is an integer Timeout san integer RetryCount is an integer TagList isa string ParamsName is a string TMask is a string of size 0 or size 6 MaxMessageSize is an integer Simple N etwork M anagement Protocol SN M P 49 Chapter 1 SNMP User s Guide 1 8 10 Target Parameters Definitions The information about Target Parameters D efinitions should be stored in a file called target_params conf The corresponding table is snmpTargetParamsTable in the SNM P TARGET M IB Each entry is aterm Param
18. 117 118 122 126 129 134 136 137 140 142 144 146 147 149 151 Chapter 1 SNMP User s Guide A multilingual Simple N etwork M anagement Protocol Extensible A gent featuring a MIB compiler and facilities for implementing SN MP MIBs etc 1 1 SNMP Introduction The SNMP development tool provides an environment for rapid agent prototyping and construction With the following information provided this tool is used to set up a running multi lingual SN M P agent e adescription of a Management Information Base MIB in Abstract Syntax N otation O ne ASN 1 e instrumentation functions for the managed objects in the MIB written in Erlang The advantage of using an extensible agent toolkit is to remove details such as type checking access rights Protocol Data Unit PDU encoding decoding and trap distribution from the programmer who only has to write the instrumentation functions which implement the MIBs The get next function only has to be implemented for tables and not for every variable in the global naming tree This information can be deduced from the ASN 1 file 1 1 1 Scope and Purpose This manual describes the SN MP development tool as a component of the Erlang O pen Telecom Platform development environment It is assumed that the reader is familiar with the Erlang D evelopment Environment which is described in a separate U ser s Guide 1 1 2 Prerequisites The following prerequisites is required for understan
19. Finally the management station could select a pseudo random number to use as the index In the event that this index was already in use and an inconsistentValue was returned in response to the management protocol set operation the management station should simply select a new pseudo random number and retry the operation A MIB designer should choose between the two latter algorithms based on the size of the table and therefore the efficiency of each algorithm For tables in which a large number of entries are expected it is recommended that a MIB object be defined that returns an acceptable index for creation For tables with small numbers of entries it is recommended that the latter pseudo random index mechanism be used Interaction 2 Creating the Conceptual Row Once an unused instance identifier has been selected the management station determines if it wishes to create and activate the conceptual row in one transaction or ina negotiated set of interactions Interaction 2a Creating and Activating the Conceptual Row The management station must first determine the column requirements i e it must determine those columns for which it must or must not provide values Depending on the complexity of the table and the management stations knowledge of the agent s capabilities this determination can be made locally by the management station Alternately the management station issues a management protocol get operation to examine al
20. IB Erlang M odule snmp_view_based_acm_mib page 147 Instrumentation Functions for SN M P VIEW BASED ACM MIB Simple N etwork M anagement Protocol SN M P 89 SNMP Reference Manual snmp No functions are exported snmp The following functions are exported e add_agent_caps SysORID SysORDescr gt SysORIndex page 101 Add an AGENT CAPABILITY definition to the agent e c File page 101 Compile the specified M IB c File Options gt ok BinFileName error Reason page 101 Compile the specified M IB e change_log_size NewSize gt ok error Reason page 102 Change the size of the Audit Trail Log config gt ok error Reason page 102 Configurate with a simple SN MP agent configuration tool e current_address gt value IP UDP false page 103 Retrieve the IP address of the manager e current_community gt value Community false page 103 Retrieve the community of the current request e current_context gt value ContextName false page 103 Retrieve the context of the current request e current_net_if_data gt value NetIfData false page 103 Retrieve the N et_if data of the current pdu e current_request_id gt value RequestId false page 103 Retrieve the request Id of the current request e date_and_time gt DateAndTime page 104 Return the current date and time as an OCTET STRING e date_and_time_to_universal_time DateAndTime gt
21. IP address and UDPport is an integer 56 Simple N etwork M anagement Protocol SN M P 1 10 Definition of Net if e Extra is any term the Net if process wishes to send to the agent This term can be retrieved by the instrumentation functions by calling snmp current net_if_data This data is also sent back to the N et if process when the agent generates a response to the request The following message is used to report that a response to a request has been received The only request an agent can send is an Inform Request Pid snmp_response_received Vsn Pdu From Pid is the Process that waits for the response for the request The Pid was specified in the send_pdu_req message see below page 58 Vsn is either version 1 version 2 Or version 3 Pdu isthe SNMP Pdu received e From is the source address If UDP over IP is used this should be a 2 tuple IP UDPport where IP is a 4 tuple with the IP address and UDPport is an integer Incoming Messages This section describes the incoming messages which a N et if process must be able to receive e snmp response Vsn Pdu Type ACMData To Extra This message is sent to the Net if process from a master agent as a response to a previously received request Vsn is either version 1 version 2 Or version 3 Pdu isan SNMP PDU record as defined in snmp _types hrl with the SN MP response Type is the pdu type of the original request ACMData
22. If there is sufficient information available then the status column is set to notInService otherwise if there is insufficient information then the status column is set to notReady Regardless we proceed to interaction 3 Interaction 3 Initializing non defaulted Objects The management station must now determine the column requirements It issues a management protocol get operation to examine all columns in the created conceptual row In the response for each column there are three possible outcomes a value is returned indicating that the agent implements the object type associated with this column and had sufficient information to provide a value For those columns to which the agent provides read create access and for which the agent allows their values to be changed after their creation a value return tells the management station that it may issue additional management protocol set operations if it desires in order to change the value associated with this column the exception noSuchInstance is returned indicating that the agent implements the object type associated with this column and that this column in at least one conceptual row would be accessible in the MIB view used by the retrieval were it to exist However the agent does not have sufficient information to provide a value and until a value is provided the Simple N etwork M anagement Protocol SN M P 65 Chapter 1 SNMP User s Guide
23. Row Vall Val2 ValN e Vall Val2 ValN term Creates a row in a table Row is a tuple with values for all columns including the index columns table_delete NameDb gt void D eletes a table table_delete_row NameDb RowIndex gt bool Deletes the row in the table table_exists NameDb gt bool Checks if a table exists table_get_row NameDb RowIndex gt Row undefined Types e Row Vall Val2 ValN e Vall Val2 ValN term Row is a tuple with values for all columns including the index columns register notify_client Client Module gt ok error Reason Types e Client term e Module atom e Reason falready_registered C urrentM odule e CurrentM odule atom Register Client as notification client to snmp_local_db Client is actually just used as an identity but could eg be a pid When changes are made to the database insert delete Or stop notify clients will be notified unregister_notify_client Client gt ok error Reason Types e Client term e Reason not_registered Unregister Client as notification client to snmp_local_db See Also ets 3 snmp_generic 3 128 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_mgr snmp_mgr Erlang M odule The module snmp_mgr provides a simple SN MP Simple N etwork M anagement Protocol manager It is used for test purposes during agent development There are two
24. The information about Security data for USM should be stored in a file called usm conf which must be present if the agent is configured for SN M Pv3 The corresponding table is usmUserTable in the SN M P USER BA SED SM M IB Each entry is a term EngineID UserName SecName Clone AuthP AuthKeyC OwnAuthKeyC PrivP PrivKeyC OwnPrivKeyC Public AuthKey PrivKey e EnginelDisastring e UserName is a string e SecName is a string e Clone iS zeroDotZero or alist of integers e AuthP iS a usmNoAuthProtocol usmHMACMD5AuthProtocol Or usmHMACSHAAuthProtocol e AuthKeyC isa string e OwnAuthKeyC is a string e PrivP iS ausmNoPrivProtocol Of usmDESPrivProtocol 48 Simple N etwork M anagement Protocol SN M P 1 8 Definition of Configuration Files PrivKeyC is a string OwnPrivKeyC is a string Public isa string AuthKey isa list of integer This is the U ser s secret localized authentication key It is not visible in the MIB The length of this key needs to be 16 if usmHMACMD5AuthProtocol is used and 20 if usmHMACSHAAuthProtocol is used PrivKey isa list of integer This is the U ser s secret localized encryption key It is not visible in the MIB The length of this key needs to be 16 if usmDESPrivProtocol is used 1 8 7 Trap Destinations The information about Trap Destinations was previously stored in a file called trap_dest conf If the agent encounters this file but not the new target configuration files see below
25. a notification send notification Agent Notification Receiver Varbinds page 109 Send a notification send_notification Agent Notification Receiver NotifyName Varbinds page 109 Send a notification Simple N etwork M anagement Protocol SN M P 91 SNMP Reference Manual e send notification Agent Notification Receiver NotifyName ContextName Varbinds gt void page 109 Send a notification e send trap Agent Trap Community page 110 Send atrap e send trap Agent Trap Community Varbinds gt void page 110 Send atrap universal_time_to_date_and_time UTC gt DateAndTime page 111 Conversa UTC value to DateAndTime unload mibs Agent Mibs gt ok error Reason page 111 Unload M IBs from the agent unregister_subagent Agent SubagentOidOrPid gt ok ok SubAgentPid error Reason page 112 Unregister a subagent validate_date_and_time DateAndTime bool page 112 Check if a DateA ndTime value is correct verbosity Ref Verbosity gt void page 112 Assign anew verbosity for the process snmp_community_mib The following functions are exported e configure ConfDir gt void page 113 Configure the SNMP COMMUNITY MIB e reconfigure ConfDir gt void page 113 Configure the SNMP COMMUNITY MIB snmp_error The following functions are exported e config err Format Args gt void page 114 Called if a configuration error occurs e user_err Format Ar
26. a oid to it s aliasname name_to_oid Name gt ok Oid error Reason Types e Name atom e Oid 0id Transform a aliasname to it s oid s Varbinds gt void Types e Varbinds varbina Sends a set request Varbind is e Oid Value if the object with Oid Oid is loaded by the manager e Oid TypeTag Value where TypeTag is sloli String O id Integer This syntax is used if this object is not defined in a M IB loaded by the manager Or if you explicitly want to send a request of wrongly typed data start Options Simple N etwork M anagement Protocol SN M P 131 snmp_mgr SNMP Reference Manual start_link Options gt void Types e Options options Starts the SN MP manager M andatary options are e agent Agent where A gent is the IP address of the agent int int int int or the name of the host string O ptional options are e agent_udp int theUDP port that the agent listens to Default is 4000 e trapudp int the UDP port where the manager will receive traps D efault is 5000 community string the community string that is sent in the requests from the manager D efault is public context string the context that is sent in v3 requests from the manager an Default is e user string theUSM user name that is sent in v3 requests from the manager D efault is initial engine_id string the engine ID of t
27. be implemented with the SNMP D evelopment Toolkit The example shown can be found in the toolkit distribution The agent is configured with the configuration tool using default suggestions for everything but the manager node 1 6 1 MIB The MIB used in this example is called EX 1 M IB It contains two objects a variable with a name and a table with friends EX1 MIB DEFINITIONS BEGIN IMPORTS RowStatus FROM STANDARD MIB DisplayString FROM RFC1213 MIB OBJECT TYPE FROM RFC 1212 examplel OBJECT IDENTIFIER experimental 7 myName OBJECT TYPE SYNTAX DisplayString SIZE 0 255 ACCESS read write STATUS mandatory DESCRIPTION My own name examplel 1 gt friendsTable OBJECT TYPE SYNTAX SEQUENCE OF FriendsEntry ACCESS not accessible STATUS mandatory DESCRIPTION A list of friends examplel 4 gt friendsEntry OBJECT TYPE SYNTAX FriendsEntry ACCESS not accessible STATUS mandatory DESCRIPTION we INDEX fIndex friendsTable 1 gt FriendsEntry SEQUENCE fIndex INTEGER fName Simple N etwork M anagement Protocol SN M P 31 Chapter 1 SNMP User s Guide DisplayString fAddress DisplayString fStatus RowStatus fIndex OBJECT TYPE SYNTAX INTEGER ACCESS not accessible STATUS mandatory DESCRIPTION number of friend friendsEntry 1 fName OBJECT TYPE SYNTAX DisplayString SIZE 0 255 ACCESS read write STATUS mandatory DESCRIPTION Name of friend
28. by the managed device createAndGo which is supplied by a management station wishing to create a new instance of a conceptual row and to have its status automatically set to active making it available for use by the managed device createAndWait which is supplied by a management station wishing to create a new instance of a conceptual row but not make it available for use by the managed device and destroy which is supplied by a management station Simple N etwork M anagement Protocol SN M P 59 Chapter 1 SNMP User s Guide wishing to delete all of the instances associated with an existing conceptual row Whereas five of the six values all except notReady may be specified in a management protocol set operation only three values will be returned in response to a management protocol retrieval operation notReady notInService or active That is when queried an existing conceptual row has only three states it is either available for use by the managed device the status column has value active it is not available for use by the managed device though the agent has sufficient information to make it so the status column has value notInService or it is not available for use by the managed device and an attempt to make it so would fail because the agent has insufficient information the state column has value notReady NOTE WELL Thi
29. conceptual row may not be made available for use by the managed device For those columns to which the agent provides read create access the noSuchInstance exception tells the management station that it must issue additional management protocol set operations in order to provide a value associated with this column the exception noSuchObject is returned indicating that the agent does not implement the object type associated with this column or that there is no conceptual row for which this column would be accessible in the MIB view used by the retrieval As such the management station cannot issue any management protocol set operations to create an instance of this column If the value associated with the status column is notReady then the management station must first deal with all noSuchInstance columns if any Having done so the value of the status column becomes notInService and we proceed to interaction 4 Interaction 4 Making the Conceptual Row Available Once the management station is satisfied with the values associated with the columns of the conceptual row it issues a management protocol set operation to set the status column to active If the agent has sufficient information to make the conceptual row available for use by the managed device the management protocol set operation succeeds a noError response is returned Otherwise the management protocol set operation fails wi
30. diff check changed according to RFC 2579 was according to RFC 1903 Own Id OTP 4209 Aux Id Seg 7185 1 13 6 SNMP Development Toolkit v3 3 3 Version 3 3 3 supports code replacement in runtime from to version 3 3 2 3 3 1 3 3 0 and 3 2 2 with the exception of what s mentioned in the version 3 3 0 note Improvements and new features Reported Fixed Bugs and Malfunctions e Erroneous macro defines corrected Own Id OTP 4006 e Storage of mib data using dets did not work see OT P 3740 Own Id OTP 4076 e Error according to section 3 2 7a of RFC 2274 2574 reported with the wrong OID usmStatsN otlInTimeW indows instead of usmStatsN otlnTimeW indows 0 O wn Id OTP 4090 1 13 7 SNMP Development Toolkit v3 3 2 Version 3 3 2 supports code replacement in runtime from to version 3 3 1 3 3 0 and 3 2 2 with the exception of what s mentioned in the version 3 3 0 note 70 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Improvements and new features Reported Fixed Bugs and Malfunctions snmp_net_if subtr 2 don t handle megaseconds O wn ld OTP 3920 Aux ld Seq 5174 The mib compiler does not detect if an notification and an ordinary mib entry OBJECT IDENTITY hasthe same O ID Own Id OTP 3986 Aux Id Seq 5256 1 138 SNMP Development Toolkit v3 3 1 Version 3 3 1 supports code replacement in runtime from to version 3 3 0 and 3 2 2 with the exception of what s mentioned in the version 3 3 0
31. for the objects in the M IB The hr1 file is called lt MibName gt hr1 The MIB must be compiled and present in the current directory The mib_to_hr1 generator can be invoked from the OS command line by using the command erlc erlc recognises the extension bin and invokes this function for files with that extension name_to_oid Name gt value oid false Types e Name atom Looks up the O BJECT IDENTIFIER of a MIB object given the symbolic name N ote the OBJECT IDENTIFIER is given for the object not for an instance false is returned if the object is not defined in any loaded M IB name_to_oid Db Name gt value oid false Types e Db term e Name atom Looks up the O BJECT IDENTIFIER of a MIB object given the symbolic name N ote the OBJECT IDENTIFIER is given for the object not for an instance Db sa reference to the symbolic store database retrieved by a call to get_symbolic_store_db 0 lt c gt lt p gt lt c gt false is returned if the object is not defined in any loaded M IB oid_to_name 0ID gt value Name false Types e OID oid e Name atom Looks up the symbolic name of a MIB object given OBJECT IDENTIFIER false is returned if the object is not defined in any loaded M IB oid_tomname Db OID gt value Name false Types e Db term e OID oid e Name atom Looks up the symbolic name of a MIB object given OBJECT IDENTIFIER Dbisa reference to the symbol
32. from all trees in Agent validate_date_and_time DateAndTime bool Types e DateAndTime term Checks if DateAndTime is a correct D ateA ndTime value as specified in RFC 1903 This function can be used in instrumentation functions to validate a D ateA ndTime value verbosity Ref Verbosity gt void Types e Ref pid snmp_master_agent snmp _net_if snmp_mib snmp _symbolic_store snmp_note_store snmp_local_db e Verbosity silence info log debug trace Sets verbosity for the designated process For the lowest verbosity silence nothing is printed The higher the verbosity the more is printed See Also calendar 3 erlc 1 112 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_community_mib snmp_community_mib Erlang Module The module snmp_community_mib implements the instrumentation functions for the SNMP COMMUNITY MIB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile All snmp counters are set to zero If an error is found in the configuration file it is reported using the function c
33. from the configuration files these rows will automatically have storage type nonVolatile Should the agent restart all nonVolatile rows survive the restart while the volatile rows are lost The configuration files are not read at restart by default This MIB is not loaded by default OTP SNMPEA MIB The OTP SN M PEA M 1B was used in earlier versions of the agent before standard M IBs existed for access control MIB views and trap target specification All objects in this MIB are now obsolete 14 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description 1 2 8 Notifications N otifications are defined in SM Iv1 with the TRAP TYPE macro in the definition of an MIB see RFC1215 The corresponding macro in SM Iv2 is NOTIFICATION TYPE When an application decides to send a notification it calls one of the following functions snmp send_notification Agent Notification Receiver NotifyName ContextName Varbinds snmp send_trap Agent Notification Community Receiver Varbinds providing the registered name or process identifier of the agent where the MIB which defines the notification is loaded and the symbolic name of the notification If the send_notification 3 4 function is used all management targets are selected as defined in RFC2273 The Receiver parameter defines where the agent should send information about the delivery of inform requests If the send_notification 5 function is used an NotifyName
34. gt RowIndex endOfTable page 120 Find the next row in the table e table_row_exists NameDb RowIndex gt bool page 120 Check if a row in a table exists e table_set_elements NameDb RowIndex Cols gt bool page 120 Set elements in a table row variable_func Op1 NameDb page 120 Default instrumentation function for tables variable func 0p2 Val NameDb gt Ret page 120 Default instrumentation function for tables variable_get NameDb gt value Value undefined page 120 Get the value of a variable e variable_set NameDb NewVal gt true false page 120 Set a value for a variable Simple N etwork M anagement Protocol SN M P 93 94 SNMP Reference Manual snmp_index The following functions are exported delete Index gt true page 123 Delete an index table delete Index Key gt NewIndex page 124 Delete an item from the index get Index Key0id gt ok Key0id Value undefined page 124 Get the item with KeyDid get_last Index gt ok KeyODid Value undefined page 124 Get the last item in the index structure get_next Index Key0id gt ok NextKey0id Value undefined page 124 Get the next item insert Index Key Value gt NewIndex page 124 Insert an item into the index key_to_oid Index Key gt Key0id page 124 Convert a key to an OBJECT IDENTIFIER new KeyTypes page 125 Create a new snmp index structure snmp_local_db The fol
35. init_mpd 1 134 process_packet 4 134 snmp_notification mib configure 1 136 reconfigure 1 136 snmp_pdus dec_message 1 137 dec_message_only 1 137 dec_pdu 1 137 dec_scoped_pdu 1 138 dec_scoped_pdu_data 1 138 dec_usm_security_parameters 1 138 156 Simple N etwork M anagement Protocol SN M P enc_encrypted_scoped_pdu 1 138 enc_message 1 138 enc_message_only 1 138 enc_pdu 1 138 enc_scoped_pdu 1 138 enc_usm_security_parameters 1 139 snmp_standard_mib configure 1 140 inc 1 140 inc 2 140 reconfigure 1 140 reinit o0 141 sys_up_time O 141 snmp_supervisor start_master 2 142 start_master 3 142 start_sub 0 142 start_sub 1 142 start_subagent 3 143 stop_subagent 1 143 snmp_target_mib configure 1 144 reconfigure 1 144 set_target_engine_id 2 145 snmp_user_based_sm_mib configure 1 146 reconfigure 1 146 snmp_view_based_acm_mib configure 1 147 reconfigure 1 147 start 1 snmp_mgr 131 start_link 1 snmp_mgr 132 start_master 2 snmp _supervisor 142 start_master 3 snmp _supervisor 142 start_sub 0 snmp _supervisor 142 start_sub 1 snmp _supervisor 142 start_subagent 3 snmp _supervisor 143 stop 0 snmp_mgr 133 Index of Modules and Functions stop_subagent 1 snmp _supervisor 143 sys_up_time 0 snmp _standard_mib 141 table_create 1 snmp_local_db 127 table_create_row 3 snmp _local_db 127 table_delete 1 snmp_local_db 128 table_delete_ro
36. instance is determined and the last part of its OBJECT IDENTIFIER and its value is returned This function is mandatory Arguments e RowIndex is a list of integers possibly empty that defines the key values for a row The RowIndex is the list representation list of integers which follow the Cols integer in the OBJECT IDENTIFIER e Cols isa list of integers greater than or equal to zero which represents the column numbers Valid Return Values e A list with as many elements as the Cols list Each element can be NextOid NextValue where NextOid is the lexicographic next OBJECT IDENTIFIER for the corresponding column This should be specified as the OBJECT IDENTIFER part following the table entry This means that the first integer is the column number and the rest is a specification of the keys NextValue is the value of this element endOfTable if there are no accessible elements after this one e genErr Column where Column denotes the column that caused the error Column must be one of the columns in the Cols list N ote that this should be an internal processing error e g a caused by a programing fault somewhere If some column does not exist you must return the next accessible element or endOfTable Simple N etwork M anagement Protocol SN M P 53 Chapter 1 SNMP User s Guide f is_set_ok RowIndex Cols ExtraArgs The fumction f is_set_ok RowIndex Cols ExtraArgs is called in phase one of the se
37. is data used by the Access Control M odule in use Normally this is just sent to snmp_mpd generate_response_message see Reference M anual To is the destination address If UDP over IP is used this should be a 2 tuple IP UDPport where IP is a 4 tuple with the IP address and UDPport is an integer Extra is the term that the Net if process sent to the agent when the request was sent to the agent e discarded_pdu Vsn Reqld ACMData Variable Extra This message is sent from a master agent if it for some reason decided to discard the pdu Vsn is either gt version 1 version 2 OF version 3 Regla is the request id of the original request ACMData is data used by the Access Control M odule in use Normally this is just sent to snmp_mpd generate_response_message see Reference M anual Variable is the name of an snmp counter that represents the error e g snmpInBadCommunityUses Extra is the term that the Net if process sent to the agent when the request was sent to the agent e send_pdu Vsn Pdu MsgData To This message is sent from a master agent when a trap is to be sent Vsn is either version 1 version 2 Or version 3 Pdu isan SNMP PDU record as defined in snmp _types hrl with the SN MP response Simple N etwork M anagement Protocol SN M P 57 Chapter 1 SNMP User s Guide MsgData is the message specific data used in the SN MP message This value is normally sent to
38. is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with reason configuration error ConfDir isa string which points to the directory where the configuration files are found The configuration file read is notify conf 136 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_pdus snmp_pdus Erlang M odule RFC1157 RFC1905 and or RFC 2272 should be studied carefully before using this module snmp_pdus The module snmp pdus contains functions for encoding and decoding of SN MP protocol data units PD Us In short this module converts a list of bytes to Erlang record representations and vice versa The record definitions can be found in the file snmp include snmp_types hr1 If sampv3 is used the module that includes snmp_types hr1 must define the constant SNMP_USE_V3 before the header file is included Example define SNMP_USE_V3 true include_lib snmp include snmp_types hrl1 Encoding and decoding must be done explicitly when writing your own Net if process Exports dec_message byte gt Message Types e Message message D ecodes a list of bytes into an SNMP Message Note if there is a v3 message the msgSecurityParameters are not decoded They must be explicitly decoded by a call to a security model specific decoding function eg decusm_security_parameters 1 Also note if the scopedPDU is encrypted the
39. list was not the same as in the input list Own Id OTP 3134 Aux Id seq1727 The record message in snmp_types hr1 has been changed to reflect the new SN M Pv3 message format Specifically the community field has changed name to vsn_hdr If the message version is vl or v2c it is still just the community string but if the version is v3 it is a v3_hdr record This change only affects applications that encodes decodes SN M P messages using the module snmp pdus If an application wants to use this new record i e it needs to use SN M Pv3 it must define the constant SNMP_USE_V3 before the header file is included This ensures that old applications that uses the old definition of message and don t use v3 don t have to be modified 1 13 21 SNMP Development Toolkit v3 0 Improvements and new features The agent is multi lingual and understands SN M Pv1 SNM Pv2c and SN M Pv3 Full SNM Pv3 support is given including encryption and authentication but the optional proxy and notification filtering features are not implemented A new function snmp send_notification 6 is added which can be used to specify from which context a notification is sent All relevant standard M IBs are included in the mibs directory in the distribution for reference purposes The agent uses the application crypto for authentication and encryption If these functions are to be used the crypto application must be started before the snmp application The manager
40. must in some way be known by the coordinator the structure of the table data determines how this is achieved The coordinator may require that the table holders explicitly register themselves and specify their information In other cases the table holders can be determined once at compile time W hen the instrumentation function for the distributed table is called the request should be forwarded to the table coordinator The coordinator finds the requested information among the table holders and then returns the answer to the instrumentation function The SNMP toolkit contains no support for coordination of tables since this must be independent of the implementation The advantages of separating the table coordinator from the SN MP tool are e We do not need a subagent for each table holder Normally the subagent is needed to take care of communication but in Distributed Erlang we use ordinary message passing e Most likely some type of table coordinator already exists This process should take care of the instrumentation for the table e The method used to present a distributed table is strongly application dependent The use of different masking techniques is only valid for a small subset of problems and registering every row in adistributed table makes it non distributed 1 7 5 Fault Tolerance The SNMP toolkit gets input from three different sources e UDP packets from the network e return values from the user defined instrumentation
41. note Improvements and new features The UDP based N etwork Interface included in this application snmp_net_if now sets the UDP receive buffer size according to the snmp _net_if_recbuf sys config option If this option is not present the default value is used i e it is not set at all There is no need to set the send buffer since the size of the send buffer is adjusted automatically N ote that the underlying IP implementation defines the maximum buffer size Own Id OTP 3874 Aux Id seq5103 Reported Fixed Bugs and Malfunctions Failure to retrieve mib info This is information specifically a list of loaded mibs is retrieved when performing a takover C ould cause a takeover to fail Own Id OTP 3890 Aux Id seq5123 Error in mib conversion for notifications This error exist only in version 3 3 0 Own Id OTP 3875 Aux Id seq4936 SNMP loop if damaged snmp db If a table row has been created with own Row Index key of this will cause an infinit loop when traversing the table this is done when the SN MP application at startup performs the table cleanup This happens if Empty string for C ommunityl ndex in config file community conf Empty string for N otifyN ame in config file notify conf Empty string for TargetN ame in config file target_addr conf Empty string for ParamsN ame in config file target_params conf Own ld OTP 3881 Aux Id seq5113 Simple N etwork M anagement Protocol SN M P 71 Cha
42. oid byteO e key_types type_spec type_spec type_spec e type_spec fix_string string integer e key key_spec key_spec key_spec e key_spec string integer Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_index The index O type denotes an snmp index structure The oid type is used to represent an ASN 1 OBJECT IDENTIFIER The key_types type is used when creating the index structure and the key type is used when inserting and deleting items from the structure The key_types O type defines the types of the SNMP INDEX columns for the table If the table has one single INDEX column this type should be a single atom but if the table has multiple INDEX columns it should be a tuple with atoms If the INDEX column is of type INTEGER or derived from INTEGER the corresponding type should be integer If it is a variable length type eg OBJECT IDENTIFIER OCTET STRING the corresponding type should be string Finally if the type is of variable length but with a fixed size restriction eg IpA ddress the corresponding type should be fix_string For example if the SNMP table has two INDEX columns the first one an OCTET STRING with size 2 and the second one an OBJECT IDENTIFER the corresponding key_types parameter would be fix_ string string The key O type correlates to the key_types O type If the key_types is a single atom the corresponding
43. only Otherwise use current_context 0 current_context gt value ContextName false Types e ContextN ame string Retrieves the context referred to in the current request It must be called from the same process that is handling the request normally an instrumentation function Returns false if no request is currently handled current_net_if_data gt value NetIfData false Types e NetlfD ata term Retrieves the N et_if data for the current pdu being handled This data is defined in the N et_if process and can be used to forward information about the packet to the instrumentation functions With the default N et_if implementation it is nil It must be called from the same process that handles the request normally an instrumentation function Returns false if no request is currently handled current_request_id gt value RequestId false Types e Requestld int Simple N etwork M anagement Protocol SN M P 103 snmp SNMP Reference Manual Retrieves the request Id of the current request It must be called from the same process that is handling the request normally an instrumentation function Returns false if no request is currently handled date_and_time gt DateAndTime Types e DateAndTime int Returns current date and time as the data type D ateA ndTime as specified in RFC 1903 Thisisan OCTET STRING date_and_time_to_universal_time DateAndTime gt UTC Types e Date
44. overwritten Ok y n e UNBE 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 The following files were written agent conf community conf standard conf target_addr conf target_params conf notify conf vacm conf sys config usm conf 1 5 3 Starting the Agent Start Erlang with the command erl config home mbj snmp_conf sys If authentication or encryption is used SN M Pv3 only start the crypto application If this step is forgotten the agent will not start but report a config error unsupported crypto error 1 gt application start crypto ok 2 gt application start snmp ok Simple N etwork M anagement Protocol SN M P 29 Chapter 1 SNMP User s Guide 1 5 4 Debugging the Agent It is possible to debug every process of the agent possibly with the exception of the net_if module which could be supplied by a user of the application This can be done in two ways Either by calling the snmp verbosity 2 function or using configuration parameters page 27 The verbosity itself has several levels silence info log debug trace For the lowest verbosity silence nothing is printed The higher the verbosity the more is printed D efault value is always silence The old debugging is still available and pr
45. page 107 Convert a Local time value to D ateA ndTime log_to_txt LogDir Mibs page 107 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile gt ok error Reason page 107 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName gt ok error Reason page 107 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName LogFile gt ok error Reason page 107 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName LogFile Start gt ok error Reason page 107 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName LogFile Start Stop gt ok error Reason page 107 Convert an Audit Trail Log to text format mib_to_hrl MibName gt ok error Reason page 108 Generate constants for the objects in the MIB name_to_oid Name gt value oid false page 108 Convert a symbolic name to an OID name_to_oid Db Name gt value oid false page 108 Convert a symbolic name to an OID oid_to_name 0ID gt value Name false page 108 Convert an OID to a symbolic name oid_tomname Db OID gt value Name false page 108 Convert an OID to a symbolic name register_subagent Agent SubTreeQid Subagent gt ok error Reason page 108 Register a subagent under a subtree send_notification Agent Notification Receiver page 109 Send
46. provide values for all columns which are missing but required then return noError and goto D 3 if other variable bindings included in the same PDU provide values for all columns which are missing but required then return noError and goto C 4 at the discretion of the agent the return value may be either inconsistentName because the agent does not choose to create such an instance when the corresponding RowStatus instance does not exist or inconsistentValue if the supplied value is Simple N etwork M anagement Protocol SN M P 61 Chapter 1 SNMP User s Guide inconsistent with the state of some other MIB object s value or noError because the agent chooses to create the instance If noError is returned then the instance of the status column must also be created and the new state is B or C depending on the information available to the agent If inconsistentName or inconsistentValue is returned the row remains in state A 5 depending on the MIB definition for the column table either noError or inconsistentValue may be returned NOTE Other processing of the set request may result in a response other than noError being returned e g wrongValue noCreation etc Conceptual Row Creation There are four potential interactions when creating a conceptual row selecting an instance identifier which is not in use creating the conceptual row initializing any objects for which the agent does not supply
47. referred to in the notification specification must be implemented by the agent that has the M IB loaded or by some parent to this agent If not the application must provide values for the unknown variables The application must also provide values for all elements in tables 1 3 Instrumentation Functions A user defined instrumentation function for each object attaches the managed objects to real resources This function is called by the agent on a get or set operation The function could read some hardware register perform a calculation or whatever is necessary to implement the semantics associated with the conceptual variable These functions must be written both for scalar variables and for tables They are specified in the association file which is a text file In this file the OBJECT IDENTIFIER or symbolic name for each managed object is associated with an Erlang tuple Module Function ListOfExtraArguments W hen a managed object is referenced in an SNMP operation the associated Module Function ListOfExtraArguments is called The function is applied to some standard arguments for example the operation type and the extra arguments supplied by the user Instrumentation functions must be written for get and set for scalar variables and tables and for get next for tables only The get bulk operation is translated into a series of calles to get next 16 Simple N etwork M anagement Protocol SN M P 1 3 Instrumentation Functio
48. request with one OID 2 gt snmpmgr gn 1 3 6 1 3 7 ok Got PDU myName 0 A set request now using symbolic names for convenience 3 gt snmpmgr s myName 0 Martin Ok Got PDU myName 0 Martin hh Try the same get next request again 4 gt snmpmgr gn 1 3 6 1 3 7 ok Got PDU myName 0 Martin h and we got the new value hh you can event do row operations How to add a row 5 gt snmpmgr s fName 0 Martin fAddress 0 home Status 0 4 createAndGO S ok Got PDU fName O Martin fAddress 0 home fStatus 0 4 6 gt snmpmgr gn myName 0 ok Got PDU fName O Martin 7 gt snmpmgr gn ok Got PDU fAddress 0 home 8 gt snmpmgr gn ok Got PDU fStatus 0 1 9 gt Simple N etwork M anagement Protocol SN M P 33 Chapter 1 SNMP User s Guide 1 6 3 Manual Implementation The following example shows a manual implementation of the EX 1 MIB in Erlang In this example the values of the objects are stored in an Erlang server The server has a 2 tuple as loop data where the first element is the value of variable myName and the second is a sorted list of rowsin the table friendsTable Each row isa 4 tuple N ote There are more efficient ways to create tables manually i e to use the module snmp_index Code module ex1 author mbj erlang ericsson se External expo
49. specific structure See RFC 2271 2571 for details 46 Simple N etwork M anagement Protocol SN M P 1 8 Definition of Configuration Files 1 8 2 Contexts The context information should be stored in a file called context conf The default context need not be present Each row defines a context in the agent This information is used in the table vacmContextTable in the SNM P V IEW BASED ACM MIB Each entry is a term ContextName e ContextName isa string 1 8 3 System Information The system information should be stored in a file called standard conf Each entry isa tuple of size two SystemVariable Value e SystemVariable is one of the variables in the system group or snmpEnableAuthenTraps e Value is the value for the variable The following example shows a valid standard conf file sysDescr Erlang SNMP agent sysObjectID 1 2 3 sysContact mbj eklas erlang ericsson se sysName test sysServices 72 snmpEnableAuthenTraps enabled A value must be provided for all variables which lack default values in the MIB 1 8 4 Communities The community information should be stored in a file called community conf It must be present if the agent is configured for SN M Pv1 or SNM Pv2c The corresponding table is snmpCommunityTable in the SNMP COMMUNITY MIB Each entry is a term CommunityIndex CommunityName SecurityName ContextName TransportTag e CommunityIndex is anon e
50. sufficient information to make the conceptual row available for use by the managed device The information available to the agent is provided by two sources the management protocol set operation which creates the conceptual row and implementation specific defaults supplied by the agent note that an agent must provide implementation specific defaults for at least those objects which it implements as read only If there is sufficient information available then the conceptual row is created a noError response is returned the status column is set to active and no further interactions are necessary i e interactions 3 and 4 are skipped If there is insufficient information then the conceptual row is not created and the set operation fails with an error of inconsistentValue On this error the management station can issue a management protocol retrieval operation to determine if this was because it failed to specify a value for a required column or because the selected instance of the status column already existed In the latter case we return to interaction 1 In the former case the management station can re issue the set operation with the additional information or begin interaction 2 again using createAndWait in order to negotiate creation of the conceptual row NOTE WELL Regardless of the method used to determine the column requirements it is possible that the management station might deem a column nec
51. supports SN M Pv3 A few new options has been added to the start function snmp_mgr start 1 Reported Fixed Bugs and Malfunctions 78 The Mib Compiler now handles forward references in OBJECT IDENTIFIERS Own Id OTP 2942 Aux Id seq1415 GET NEXT on an empty table implemented with snmp_generic returns correctly Own Id OTP 2979 Aux Id seq1496 The functions snmp log_to_text 2 3 can be used when the log is opened and in use by the agent Own Id OTP 2994 Aux Id seq1508 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Incompatibilities with v2 2 x The OTP SN MPEA MIB is not used anymore The functionality is provided by standard MIBs This means that managers that are using this MIB should use the standard M IBs instead Applications that include the header file OTP SNMPEA MIB hr1 need to be changed The handling of data in the configuration files vs data in the actual tables is reworked and made consistent This means that data changed by a manager survives a reboot if the manager so wishes by using the StorageType columns in the tables There is a new configuration parameter force_config_load which can be set to true to get the old behaviour i e that the configuration files are always read at startup The configuration files address conf view conf and trap dest conf are not used anymore The formats of agent conf and community conf have changed context conf usm conf and vacm conf are new fi
52. the DESCRIPTION clause it is suggested that this period be approximately 5 minutes in length This removal action applies not only to newly created rows but also to previously active rows which are set to and left in the notInService state for a prolonged period exceeding that which is considered normal for such a conceptual row Conceptual Row Suspension When a conceptual row is active the management station may issue a management protocol set operation which sets the instance of the status column to notInService If the agent is unwilling to do so the set operation fails with an error of wrongValue Otherwise the conceptual row is taken out of service and a noError response is returned It is the responsibility of the DESCRIPTION clause of the status column to indicate under what circumstances the status column should be taken out of service e g in order for the value of some other column of the same conceptual row to be modified Conceptual Row Deletion For deletion of conceptual rows a management protocol set operation is issued which sets the instance of the status column to destroy This request may be made regardless of the current value of the status column e g it is possible to delete conceptual rows which are either notReady notInService or active If the operation succeeds then all instances associated with the conceptual row are immediately removed INTEGER
53. the agent i e requests which will gererate large responses Also consider the max size of the agents outgoing message defined eg by snmpEngineM axM essageSize in SNM P FRAMEWORK M IB Default is 1024 132 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_mgr stop gt void Stopsthe SN MP manager Simple N etwork M anagement Protocol SN M P 133 snmp_mpd SNMP Reference Manual snmp_mpd Erlang Module The module snmp_mpd implements the version independent M essage Processing and Dispatch functionality in SN MP It is supposed to be used from a N etwork Interface process net_if Exports init_mpd Options gt mpd_state Types e Options 0 ption e Option v1 v2 v3 This function can be called from the net_if process at startup The options list defines which versions to use It also initializes some SN MP counters process_packet Packet TDomain TAddress State gt ok Vsn Pdu PduMS ACMData discarded Reason Types e Packet binary TDomain snmpUD PD omain TAddress Ip U dp Ip integer integer integer integer Udp integer State mpd_state e Vsn version 1 version 2 version 3 Pdu pdu PduMs integer ACM Data acm_data Processes an incoming packet Performs authentication and decryption as necessary The return values should be passed the agent generate responsemsg Vsn RePdu Type ACMData
54. the configuration files e starting the agent e debugging the agent Refer also to the chapter D efinition of Configuration Files page 46 which contains more detailed information about the configuration files 1 5 1 Configuring the Agent The following two directories must exist in the system e the configuration directory stores all configuration files refer to the chapter D efinition of Configuration Files page 46 for more information e the database directory stores the internal database files The agent 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 audit_trail_log false write_log read_write_log lt optional gt Specifies if an audit trail log should be used The disk_log module is used to maintain a wrap log If write_log is specified only set requests are logged If read_write_log all requests are logged D efault is false audit_trail_log_dir string lt optional gt Specifies where the audit trail log should be stored If audit_trail_log specifies that logging should take place this parameter must be defined audit_trail_log size MaxBytes MaxFiles lt optional gt Specifies the size of the audit trail log This parameter is sent to disk_log If audit_trail_log specifies that logging should take place this paramete
55. the leaves in the tree Own Id OTP 1319 84 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions The agent now treats the SN M Pv2 error value wrongValue correctly Own Id OTP 1162 It is now possible to load M IBs with short names Own Id OTP 1195 The MIB compiler now compiles full path files Own Id OTP 1217 The function snmp config 0 works for WinNT Own Id OTP 1216 The agent handles bad index returned from table instrumentation functions Own Id OTP 1222 The data type IpAddress works better Own Id OTP 1234 The function snmp date_and_time 0 now works correctly when called at midnight Own Id OTP 1236 The documentation of snmp_generic table_set_elements 3 is updated to reflect the fact that it is the caller s responsibility to call this function from within a transaction if M nesia is used Own ld OTP 1265 The MIB compiler prints the error message U nexpected 0 when an INTEGER begins with 0 Own Id OTP 1274 The agent now decodes negative integers correctly Own Id OTP 1298 Trying to delete a non existing row implemented with snmp_generic now returns noError instead of inconsistentValue Own ld OTP 1331 Default value initialisation now works for M nesia tables when snmp_generic table_set_row 5 iS called Own Id OTP 1338 Trying to set arow implemented with snmp_generic when an INDEX column was read write got the agent into an infinite
56. which always is the case at failover Now the SN MP related M nesia table is defined to have the local_content property Own Id OTP 2146 Aux Id seql 1 13 27 SNMP Development Toolkit v2 1 1 Reported Fixed Bugs and Malfunctions The snmp_note_store server sometimes didn t invoked its gc which meant that its internal data structure could grow very large Own Id OTP 1946 OT P 2004 Aux Id seq451 If a possibly user defined net if process crahses and restarts the agent could crash as well Own Id OTP 2017 Failover takeover of the SN MP agent administering the MIB did not work since the old implementation tried to delete a M nesia table on a node which was not up and running which always is the case at failover Now the SN MP related M nesia table is defined to have the local_content property Own Id OTP 2146 Aux Id seql 1 13 28 SNMP Development Toolkit v2 1 Improvements and new features The agent does not use the application sockets anymore Thus sockets does not have to be started before the agent or manager There are several new functions in the module snmp to check the syntax of and convert to from DateAndTime structures Reported Fixed Bugs and Malfunctions 82 If an is_set_ok or undo instrumentation function crashed because it called an undefined function the agent treated this as if the instrumentation function succeeded Own Id OTP 1762 Aux Id seq369 The function snmp date_and_time 0 retur
57. 3 0 o o 71 1 13 9 SNMP Development Toolkit v3 3 0 0 o o e 72 1 13 10SNMP Development Toolkit v3 2 2 0 oo eee 72 1 13 115N MP Development Toolkit v3 2 1 o o e 73 1 13 125N MP Development Toolkit v3 2 0 0 o e 73 1 13 133N MP Development Toolkitv3 1 4 0 ooo o 74 1 13 14SNMP Development Toolkit v3 1 3 0 ooo ee 74 1 13 155N MP Development Toolkit v3 1 2 0 o oe 75 1 13 16SN MP Development Toolkit v3 1 0 ooo o 76 1 13 17SNMP Development Toolkitv3 1 0 o oo 77 1 13 18SNMP Development Toolkitv3 0 3 0 o o 77 1 13 19N MP Development Toolkitv3 0 2 00 0 0 00000 eee 77 1 13 20SNMP Development Toolkitv3 0 1 0 0 0 0 00002 ee 78 1 13 21SNMP Development Toolkitv3 0 o ooo e 78 1 13 225N MP Development Toolkit V2 2 3 0 o o 79 1 13 233N MP Development Toolkit v2 2 2 0 o o e 79 1 13 24SNMP Development Toolkit v2 2 1 0 0 0 0 0000024 80 1 13 255N MP Development Toolkit v2 2 0 ooo e 80 1 13 26SNMP Development Toolkit v2 1 0 2 2 0 0 0000000008 81 1 13 27SNMP Development Toolkitv2 1 1 0 2 2 0 02000200008 82 1 13 285N MP Development Toolkit v2 1 00 2 0 0000002 82 1 13 205N MP De
58. 570 2575 O ver time as the Framework has evolved from SN M Pv1 through SN MPv2 to SNM Pv3 the definitions of each of these architectural components have become richer and more clearly defined but the fundamental architecture has remained consistent The main features of SNM Pv2 compared to SN M Pv1 are e The get bulk operation for transferring large amounts of data e Enhanced error codes e A more precise language for MIB specification 4 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description The standard documents that define SN M Pv2 are incomplete in the sense that they do not specify how an SN M Pv2 message looks like The message format and security issues are left to a special Administrative Framework O ne such framework is the Community based SN M Pv2 Framework SNM Pv2c which uses the same message format and framework as SN M Pv1 Other experimental frameworks as exist e g SN M Pv2u and SN M Pv2 The SN M Pv3 specifications take a modular approach to SNMP All modules are separated from each other and can be extended or replaced individually Examples of modules are M essage definition Security and Access Control The main features of SN M Pv3 are e Encryption and authentication is added e MIBs for agent configuration are defined All these specifications are commonly referred to as SN M Pv3 but it is actually only the M essage module which defines a new message format and Security
59. 8 Encode an encrypted SN MP scopedPD U e enc _message Message gt byte page 138 Encode an SN MP M essage e enc_message_only Message gt byte page 138 Encode an SN MP M essage but not the data part Simple N etwork M anagement Protocol SN M P SNMP Reference Manual e enc_pdu Pd gt byte page 138 Encode an SNMP Pdu e enc_scoped_pdu ScopedPdu gt byteQ page 138 Encode an SNMP scopedPD U e enc_usm_security_parameters UsmSecParams gt byte page 139 Encode SN MP UsmSecurityParameters snmp _standard_mib The following functions are exported e configure ConfDir gt void page 140 Configure the STANDARD MIB and SN MPv2 MIB e inc Name gt void page 140 Increment a variable in the MIB e inc Name N gt void page 140 Increment a variable in the MIB e reconfigure ConfDir gt void page 140 Configure the STANDARD MIB and SN MPv2 MIB reinit gt void page 141 Reset all snmp counters to 0 e sys_up_time gt Time page 141 Get the system up time snmp _supervisor The following functions are exported e start_sub page 142 Start the SN MP supervisor for subagents only e start_sub Opts gt fox pid error already_started pid error Reason page 142 Start the SNMP supervisor for subagents only e start_master DbDir ConfDir page 142 Start the SNMP supervisor for all agents e start_master DbDir ConfDir Opts gt f
60. AndTime int e UTC Y Mo D H M S Converts a DateA ndT ime list to universal time The unversal time value on the same format as defined in calendar 3 date_and_time_to_string DateAndTime gt string Types e DateAndTime int Converts a DateA ndTime list to a printable string according to the DISPLAY HINT definition in RFC 1903 debug Agent Bool gt void Types e Agent pid atom e Bool bool Turns debugging of the agent on off Debug information is printed whenever an instrumentation function is called and when a packet is received or sent This actually sets verbosity to Log or silence for the snmp_master_agent and snmp_net_if del_agent_caps SysORIndex gt void Types e SysO RIndex integer This function can be used to delete an AGENT CAPABILITY statement to the sysO RTable in the agent This table is defined in the SN M Pv2 M IB enum_to_int Name Enum gt value Int false Types e Name atom e Enum atom e Int int 104 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB The MIB must be loaded false is returned if the object or type is not defined in any loaded M IB or if it does not define the symbolic value as enumerated enum_to_int Db Name Enum gt value Int false Types e Db term e Name atom e Enum ato
61. Chapter 1 SNMP User s Guide SNMP VIEW BASED ACM MIB The SN MP VIEW BASED ACM MIB defines managed objects to control access to the the managed objects for the managers The View Based Access Control Module VACM can be used with any SN MP version However if it is used with SN M Pv1 or SNM Pv2c the SNMP COMMUNITY MIB defines additional objects to map community strings to VACM parameters All tables in this MIB have acolumn of type StorageType The value of this column specifies how each row is stored and what happens in case of a restart of the agent The implementation supports the values volatile and nonVolatile When the tables are initially filled with data from the configuration files these rows will automatically have storage type nonVolatile Should the agent restart all nonVolatile rows survive the restart while the volatile rows are lost The configuration files are not read at restart by default This MIB is not loaded by default VACM is described in detail in RFC2275 Here is only a brief description given The basic concept is that of a M IB view An MIB view is a subset of all the objects implemented by an agent A manager has access to a certain MIB view depending on which security parameters are used in which context the request is made and which type of request is made The following picture gives an overview of the mechanism to select an M IB view gt securityModel __ who groupName _____
62. DOS gt 2 gt snmpmgr s myName 0 Klas ok Got PDU Received a trap Generic 4 authenticationFailure Enterprise iso 2 3 Specific 0 Agent addr 123 12 12 21 TimeStamp 42993 2 gt AGENT 3 gt snmp send_trap snmp_master_agent fTrap standard trap fIndex 2 2 MANAGER 2 gt Got PDU Received a trap Generic 6 Enterprise example1 Specific 1 Agent addr 123 12 12 21 TimeStamp 69649 myName 0 Martin fIndex 2 2 2 gt 1 7 Advanced Topics The chapter Advanced Topics describes the more advanced features of the SNMP development tool The following topics are covered e When to use a Subagent e Agent semantics e Subagents and dependencies e Distributed tables e Fault tolerance e Using Mnesia tables as SN MP tables e Audit Trail Logging e Deviations from the standard 1 7 1 When to use a Subagent The section W hen to use a Subagent describes situations where the mechanism of loading and unloading M IBs is insufficient In these cases a subagent is needed Simple N etwork M anagement Protocol SN M P 39 Chapter 1 SNMP User s Guide Special Set Transaction Mechanism Each subagent can implement its own mechanisms for set get and get next For example if the application requires the get mechanism to be asynchronous or needs a N phase set mechanism a specialized subagent should be used The toolkit allows different kinds of subagents at the same time According
63. Development Toolkit v1 2 Improvements and new features 86 A new set phase undo is added When the agent has called is_set_ok for an object it will always call either set or undo at a later stage This may be used to reserve resources in the is_set_ok function M ore documentation on M nesia Added conversion functions from O BJECT IDENTIFIER to symbolic name and vice versa These are called snmp oid_to_name 1 and snmp name_to_oid 1 Added conversion functions from enumerated integers to symbolic value and vice versa These are called snmp int_to_enum 2 and snmp enum_to_int 2 Added an extra parameter from the configurable N et If process for each SNMP packet This value can be retrieved by snmp current_net_if_data 0O from an instrumentation function Added a function snmp date_and_time O which returns a DateA ndTime value according to RFC 1903 A new function snmp str_apply 1 may be used to pass options to the M ib Compiler from the unix command line There is now no need to have a RowStatus column for a read only table that is implemented with snmp_generic A Mnesia table that implements an SNMP table with snmp_generic may have more columns than the SNMP table Added a function snmp get 2 to retrieve values from the agent from programs The snmp config 0 tool handles host names as strings better The Mib Compiler generates better warnings The agent handles atoms as return values from enumerated integers better
64. Id Reported Fixed Bugs and Malfunctions 76 Conversion of a log to text format could crash SN MP if the log was already open Own Id OTP 3261 Aux Id seq3884 The BER encoding of integers did not follow the ASN 1 BER encoding rules Own Id OTP 3274 Aux Id seq3960 SN MP did not start if the audit disk_log file was corrupt Own Id OTP 3290 Aux Id SN MP was not backward compatible with instrumentation functions that returned noValue unSpecified the SNMP agent crashed This has been changed by silently transforming such a return value to noValue noSuchInstance Own ld OT P 3303 Aux Id seq3975 The header file snmp_vacm hr1 was missing in the SNMP src directory Own Id OTP 3327 Aux ld Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Incompatibilities with v3 1 e Applications that parses the audit trail log text files have to be rewritten 1 13 17 SNMP Development Toolkit v3 1 Improvement and new features e Adaption to new format of exit codes 1 13 18 SNMP Development Toolkit v3 0 3 Improvements and new features e A new function snmp date_and_time_to_string 1 has been added It converts a DateAndTime octet string to a string according to the DISPLAY HINT in RFC1903 e A new function snmp target_mib set_target_engine_id 2 has been added It Reported Fixed Bugs and Malfunctions e get next on vacmA ccessTable finds all columns Own Id OT P 3187 Aux Id seq3647 The
65. L securityName where contexrName ViewName gt securityModel who Ls securityLevel why gt viewType read write notify Figure 1 4 Overview of the mechanism of MIB selection vacmContextTable The vacmContextTable is a read only table that lists all available contexts 12 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description vacmSecurityToGroupTable The vacmSecurityToGroupTable Maps a securityModel and a securityName to a groupName vacmAccessTable The vacmAccessTable maps the groupName found in vacmSecurityToGroupTable contextName securityModel and securityLevel to an MIB view for each type of operation read write or notify The MIB view is represented as a viewName The definition of the MIB view represented by the viewName is found in the vacmViewTreeFamilyTable vacmViewTreeFamilyTable The vacmViewTreeFamilyTable is indexed by the viewName and defines which objects are included in the MIB view The MIB definition for the table looks as follows VacmViewTreeFamilyEntry SEQUENCE vacmViewTreeFamilyViewName SnmpAdminString vacmViewTreeFamilySubtree OBJECT IDENTIFIER vacmViewTreeFamilyMask OCTET STRING vacmViewTreeFamilyType INTEGER vacmViewTreeFamilyStorageType StorageType vacmViewTreeFamilyStatus RowStatus INDEX vacmViewTreeFamilyViewName vacmViewTreeFamilySubtree Each vacmViewTreeFamilyViewName refers to a collec
66. M Pv1 error codes by the agent if necessary N ote The translation from an SM Iv1 MIB to an SNM Pv2c or SNM Pv3 reply is always very straightforward but the translation from a v2 MIB to a v1 reply is somewhat more complicated There is one data type in SM lv2 called Counter64 that an SN M Pv1 manager cannot decode correctly Therefore an agent may never send a Counter64 object to an SNM Pv1 manager The common practice in these situations is to simple ignore any Counter64 objects when sending a reply or a trap to an SNM Pv1 manager For example if an SNM Pv1 manager tries to GET an object of type Counter64 he will get a noSuchName error while an SNM Pv2 manager would get a correct value 1 2 4 Operation The following steps are needed to get a running agent 1 Write your MIB in SMI in a text file 2 Write the instrumentation functions in Erlang and compile them 3 Put their names in the association file 4 Run the MIB together with the association file through the MIB compiler Simple N etwork M anagement Protocol SN M P 5 Chapter 1 SNMP User s Guide 5 Configure the agent 6 Start the agent 7 Load the compiled MIB into the agent The figures in this section illustrate the steps involved in the development of an SN MP agent sysContact OB ECT TYPE Association file file funcs SYNTA DisplayString sysContact mymod sysCFunc MIB Compiler Binary Representation Figure 1 1 MIB Compiler Princip
67. MibN ame e MibName string Loads Mibs into an agent If the agent cannot load all MIBs it will indicate where loading was aborted The MibName is the name of the Mib including the path to where the compiled mib is found For example 106 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp Dir code priv_dir my_app mibs snmp load_mibs snmp_master_agent Dir MY MIB local_time_to_date_and_time Local gt DateAndTime Types e Local Y Mo D H M S e DateAndTime int Converts a local time value to a D ateAndTime list The local time value on the same format as defined in calendar 3 log_to_txt LogDir Mibs log_to_txt LogDir Mibs OutFile gt ok error Reason log_to_txt LogDir Mibs OutFile LogName gt ok error Reason log_to_txt LogDir Mibs OutFile LogName LogFile gt ok error Reason log to_txt LogDir Mibs OutFile LogName LogFile Start gt ok error Reason log to_txt LogDir Mibs OutFile LogName LogFile Start Stop gt ok ferror Reason Types e LogDir string e Mibs MibN ame e OutFile string e MibN ame string e LogName string e LogFile string e Start Stop null datetime local_timedatetime universal_time datetime 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 replac
68. N M P 17 Chapter 1 SNMP User s Guide Is set ok Operation Asa complement to the set operation it is possible to specify a test function This function has the same syntax as the set operation above except that the first argument is is_set_ok instead of set This function is called before the variable is set Its purpose is to ensure that it is permissible to set the variable to the new value variable_access is_set_ok NewValue ExtraArgl For tables table_access set RowIndex Cols ExtraArgl1 Cols is alist of tuples Column NewValue Undo Operation A function which has been called with is_set_ok will be called again either with set if there was no error or with undo if an error occurred In this way resources can be reserved in the is_set_ok operation released in the undo operation or made permanent in the set operation variable_access undo NewValue ExtraArgl For tables table_access set RowIndex Cols ExtraArgl1 Cols is alist of tuples Column NewValue GetNext Operation The GetN ext O peration operation should only be defined for tables since the agent can find the next instance of plain variables in the M IB and call the instrumentation with the get operation table_access get_next RowIndex Cols ExtraArg1 Cols is alist of integers all greater than or equal to zero This indicates that the instrumentation should find the next accessible instance This function
69. N MP agent e a MIB compiler e a simple manager Configuration The following configuration parameters are defined for the SN MP application Refer to application 3 for more information about configuration parameters audit_trail_log false write_log read write_log lt optional gt Specifies if an audit trail log should be used The disk_log module is used to maintain a wrap log If write_log is specified only set requests are logged If read_write_log all requests are logged D efault is false audit_trail_log dir string lt optional gt Specifies where the audit trail log should be stored If audit_trail_log specifies that logging should take place this parameter must be defined audit_trail_log size MaxBytes MaxFiles lt optional gt Specifies the size of the audit trail log This parameter is sent to disk_log If audit_trail_log specifies that logging should take place this parameter must be defined bind_to_ip_address bool lt optional gt If true the agent binds to the agent IP adress If false the agent listens on any IP address on the host where it is running D efault is false force_config_load bool lt optional gt If true the configuration files are re read during startup and the contents of the configuration database ignored Thus if true changes to the configuration database are lost upon reboot of the agent D efault is false no_reuse_address bool lt optional gt If true the agent does not
70. N MP table The SN MP tables are stored in M nesia tables with the same names as the SN MP tables All functions assume that a M nesia table exists with the correct name and attributes It is the programmer s responsibility to ensure this Specifically if variables are stored in M nesia the table snmp_variables must be created by the programmer The record definition for this table is defined in the file snmp include snmp_types hrl If an instrumentation function in the association file for a variable myVar does not have a name when compiling an M IB the compiler generates an entry myVar snmp_generic variable_func myVar Db 118 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _generic And for a table myTable snmp_generic table_func myTable Db In the functions defined below the following types are used NameDb Name Db Name atom Db volatile persistent mnesia RowIndex int Cols Col Col Value Col int Value term RowIndex denotes the last part of the OID which specifies the index of the row in the table see RFC 1212 4 1 6 for more information about INDEX Cols isa list of column numbers in the case of a get operation and a list of column numbers and values in the case of a set operation Cols isa list of column numbers in case of a get operation and a list of column numbers and values in case of a set operation Exports get_status_col Na
71. N etwork M anagement Protocol SN M P 105 snmp SNMP Reference Manual info Agent gt Key Value Types e Agent pid atom Returns a list a dictionary containing information about the agent Information includes loaded M IBs registered subagents some information about the memory allocation int_to_enum Name Int gt value Enum false Types e Name atom e Int int e Enum atom Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB The MIB must be loaded false is returned if the object or type is not defined in any loaded MIB or if it does not define the symbolic value as enumerated int_to_enum Db Name Int gt value Enum false Types e Db term e Name atom e Int int e Enum atom Converts the integer Int to the corresponding symbolic value of the enumerated object or type Name in a MIB The MIB must be loaded Db is a reference to the symbolic store database retrieved by a call to get_symbolic_store db 0 lt c gt lt p gt lt c gt falseis returned if the object or type is not defined in any loaded M IB or if it does not define the symbolic value as enumerated is_consistent Mibs gt ok error Reason Types e Mibs MibN ame e MibName string Checks for multiple usage of object identifiers and traps between MIBs load_mibs Agent Mibs gt ok error Reason Types e Agent pid atom e Mibs
72. OCTET STRING encoded encryptedPDU will be present in the data field dec_message_only byte gt Message Types e Message message D ecodes a list of bytes into an SN MP Message but does not decode the data part of the M essage That means data is still a list of bytes normally an encoded PDU v1 and V 2 or an encoded and possibly encrypted scopedPDU v3 dec_pdu byte gt Pdu Types e Pdu pdu Decodes a list of bytes into an SNMP Pdu Simple N etwork M anagement Protocol SN M P 137 snmp_pdus SNMP Reference Manual dec_scoped_pdu byte gt ScopedPdu Types e ScopedPdu scoped_pdu Decodes a list of bytes into an SN MP ScopedPdu dec_scoped_pdu_data byte gt ScopedPduData Types e ScopedPduD ata scoped_pdu EncryptedPD U e EncryptedPDU byte Decodes a list of bytes into either a scoped pdu record or if the scoped pdu was encrypted to alist of bytes dec_usm_security_parameters byte gt UsmSecParams Types e UsmSecParams usmSecurityParameters Decodes a list of bytes into an SN MP UsmSecurityParameters enc_encrypted_scoped_pdu EncryptedScopedPdu gt byte Types e EncryptedScopedPdu byte Encodes an encrypted SN MP ScopedPdu into an OCTET STRING that can de used as the data field in a message record that later can be encoded with a call to enc_message_only 1 This function should be used whenever the ScopedPDU is encrypted enc_message Message g
73. Otherwise row is modified check that row exists UNT gt friends_table is_set_ok RowIndex Cols gt RowExists case get_row RowIndex of fok _Row gt true _ gt false end case is_row_status_col_changed Cols of true destroy when RowExists true gt noError 0 true createAndGo when RowExists false length Cols 3 gt noError O true _ gt inconsistentValue status_col false when RowExists true gt noError 0 _ gt 4Co1 _NewVal _Cols Cols inconsistentName Col end friends_table set RowIndex Cols gt case is_row_status_col_changed Cols of true destroy gt exi_server self delete_row RowIndex true createAndGo gt NewRow make_row RowIndex Cols exi_server self fadd_row NewRow false gt lok Row get_row RowIndex NewRow merge_rows Row Cols exi_server self delete_row RowIndex exi_server self fadd_row NewRow Simple N etwork M anagement Protocol SN M P 35 Chapter 1 SNMP User s Guide end noError 0 get_cols Col Cols Row gt value element Col Row get_cols Cols Row get_cols _Row gt O Tifa e eae aeeae e hh AS get_cols but the Cols list may contain invalid column numbers If it does we must find the next valid column or return endOfTable R OE E E E get_next_cols Col Cols Row when Col lt 2 gt 2 element 1 Row element 2
74. P 3525 Aux Id seq4391 the SNMP reportableFlag was set in response messages which it should not Own Id OTP 3416 Aux Id seq4200 Failure to check if MIBs were already loaded at take over Own Id OTP 3411 Aux Id seq4155 Unneccessary print outs in snmp_net_if O wn Id OTP 3410 Aux ld seq4241 A crash report from disk_log was generated when the SN MP agent was started for the very first time O wn ld OTP 3393 Aux ld seq4211 The SN MP agent crashed in snmp_pdus enc_oid_tag during initialization of table Proper check of object identifier values has been added Own Id OTP 3378 Aux Id seq4155 1 13 15 SNMP Development Toolkit v3 1 2 Version 3 1 2 supports code replacement in runtime from versions 3 1 1 and 3 0 6 Improvements and new features The fact that the MIBs SN M Pv2 SM 1 RFC 1215 RFC 1212 SNM Pv2 TC SNM Pv2 CONF and RFC1155 SM are compiler built ins has been added to the compiler documentation Own Id OTP 3316 Aux Id The agent option authentication_service has been reintroduced This option is part of an SNMP internal API Own Id OTP 3324 Aux ld It has been clarified in the documentation that the value of snmpEngineID should not be just a simple string but has to follow the conventions specified in RFC 2271 2571 Own Id OT P 3350 Aux ld Reported Fixed Bugs and Malfunctions If two Erlang nodes are started on the same host and each node starts an SN MP agent and if both agents
75. Reference Manual snmp_generic Erlang Module The module snmp_generic contains generic functions for implementing tables and variables using the SN MP built in database or M nesia These default functions are used if no instrumentation function is provided for a managed object in a MIB Sometimes it might be necessary to customize the behaviour of the default functions For example in some situations a trap should be sent if a row is deleted or modified or some hardware is to be informed when information is changed The overall structure is shown in the following figure 4 SNMP Agent ta MIB 4 Association file associates a MIB object with snmp_generic table_funct snmp_generic variable_func 4 snmp_generic Support for get next RowStatus operations snmp local db Mnesia Database 4 4 pets Adds Persistent P ASA properties to ets ets The standard Erlang ca ee A O module Each function takes the argument NameDb which is atuple Name Db to identify which database the functions should use Name is the symbolic name of the managed object as defined in the M IB and Db is either volatile persistent Or mnesia If it is mnesia all variables are stored in the M nesia table snmp_variables which must be a table with two attributes not a M nesia S
76. Row get_next_cols Cols Row get_next_cols Col Cols Row when Col gt 4 gt end0fTable get_next_cols Cols Row get_next_cols Col Cols Row gt Col element 1 Row element Col Row get_next_cols Cols Row get_next_cols _Row gt O end_of_table Col Cols gt end0f Table end_of_table Cols end_of_table gt O add_one_to_cols Col Cols gt Col 1 add_one_to_cols Cols add_one_to_cols gt O is_row_status_col_changed Cols gt case lists keysearch status_col 1 Cols of value status_col StatusVal gt true StatusVal _ gt false end get_row RowIndex gt exi_server self get_row RowIndex wait_answer get_next_row RowIndex gt exi_server self get_next_row RowIndex wait_answer wait_answer gt receive exi_server Answer gt Answer 36 Simple N etwork M anagement Protocol SN M P 1 6 Implementation Example initQ gt register ex1_server self loop 0 loop MyName Table gt receive From get_my_name gt From ex1_server MyName loop MyName Table From set_my_name NewName gt loop NewName Table From get_row RowIndex gt Res table_get_row Table RowIndex From ex1_server Res loop MyName Table From get_next_row RowIndex gt Res table_get_next_row Table RowIndex From exi_server Res loop MyName Table From
77. Simple Network Management Protocol SNMP version 3 3 Typeset in IATEX from SGML source using the DOCBUILDER 3 2 2 Document System Contents 1 SNMP User s Guide 1 1 SNMP Introduction edad Ra a a ELT Scopesand Purpose is sce eee Go beet ea AA BOR eal Bees 1 1 2 gt Prerequisites a angh aici a meee cds WM Ar at chant ube FLS lt A bout THIS Manual vow ee eo bees eka aaa aN Se a ae RE a 1 1 4 Whereto Find More Information o e 24 eee 1 2 Functional Deescription ri dd daa L251 Deninitions a A a 1 2 2 gt EOALUMOS 5 cece A RA A AAA A A a 1 2 3 SNMPv1 SNMPv2 andSNMPv3 o e es 1 24 Operation ona e a a dd OP ta 1 2 5 SubagentsandMIBLoading 2 000 o e 1 2 6 Contexts and Communities o o e 1 2 7 Management of the Agent 0 0 00 12 8 N OtITICACIONS i s aoa wetter ea acne AAA A a 1 3 Instrumentation Functions o o e eee 1 3 1 Instrumentation Functions o o e 1 3 2 Using the ExtraArqument uv a a eee 1 3 3 Default Instrumentation o o ee 1 3 4 A TQMIESEO e E a de dede ae SA 1 4 gt The MIB Compiler vrai A he eek Bee we ER Bee ed 14 1 Operation s ro 2 5 si vee SRR Eee ee aoe ee ae a EA eS 1 4 2 Importing MIBS 34s a a8 etek ts Adds wih AA er 1 43 MIB Consistency Checking 0 00 1 4 4 hrl FileGeneration 2 o e ea aa 14 5 Emacs Integration aio dt BAA iee
78. Stops the subagent on the node where the function is called The snmp_supervisor must be running If the supervisor is not running the function fails with the reason badarg Simple N etwork M anagement Protocol SN M P 143 snmp_target mib SNMP Reference Manual snmp_target_mib Erlang Module The module snmp_target_mib implements the instrumentation functions for the SN M P TARGET M IB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration error ConfDir isa string which points to the directory where the configuration files are found The configuration files read are target_addr conf and target_params conf reconfigure ConfDir gt void Types e ConfDir string Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configura
79. US mandatory DESCRIPTION A table with information about employees emp 1 empEntry OBJECT TYPE SYNTAX EmpEntry ACCESS not accessible STATUS mandatory DESCRIPTION INDEX 1 empDepNo empName empTable 1 gt EmpEntry SEQUENCE empDepNo INTEGER empName DisplayString empTelNo DisplayString empStatus RowStatus J The corresponding M nesia table is specified as follows mnesia create_table name employees snmp key integer string attributes key telno row_status N ote In the M nesia tables the two key columns are stored as a tuple with two elements Therefore the arity of the table is 3 Simple N etwork M anagement Protocol SN M P 43 Chapter 1 SNMP User s Guide Instrumentation Functions The MIB table shown in the previous section can be compiled as follows 1 gt snmp c EmpMIB db mnesia This is all that has to be done N ow the manager can read add and modify rows Also you can use the ordinary M nesia API to access the table from your programs The only explicit action is to create the M nesia table an action the user has to perform in order to create the required table schemas Adding Own Actions It is often necessary to take some specific action when a table is modified This is accomplished with an instrumentation function It executes some specific code when the table is set and passes all other requests down to the pre defined function The following e
80. UTC page 104 Convert a DateA ndTime value to UTC e date_and_time_to_string DateAndTime gt string page 104 Convert a DateA ndTime value to a string debug Agent Boo1 gt void page 104 Turn debugging on off e del_agent_caps SysORIndex gt void page 104 Delete an AGENT CAPABILITY definition from the agent e enum_to_int Name Enum gt value Int false page 104 Convert an enum value to an integer e enum_to_int Db Name Enum gt value Int false page 105 Convert an enum value to an integer e get Agent Vars gt Values error Reason page 105 Perform a get operation on the agent e get_agent_caps gt SysORIndex SysORID SysORDescr SysORUpTime page 105 Return all AGENT CAPABILITY definitions in the agent 90 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual get_symbolic_store_db gt Db page 105 Retrieve the symbolic store database reference info Agent gt Key Value page 106 Return information about the agent int_to_enum Name Int gt value Enum false page 106 Convert an integer to an enum value int_to_enum Db Name Int gt value Enum false page 106 Convert an integer to an enum value is_consistent Mibs gt ok error Reason page 106 Check for OID conflicts between MIBs load_mibs Agent Mibs gt ok error Reason page 106 Load M IBs into the agent local_time_to_date_and_time Local gt DateAndTime
81. _mib 140 snmp_target_mib 144 snmp_user_based_sm_mib 146 snmp_view_based_acm_mib 147 register_notify_client 2 snmp_local_db 128 register_subagent 3 snmp 108 reinit 0 snmp_standard_mib 141 s 1 snmp_mgr 131 send_notification 3 Index of Modules and Functions snmp 109 send_notification 4 snmp 109 send_notification 5 snmp 109 send_notification 6 snmp 109 send_trap 3 snmp 110 send_trap 4 snmp 110 set_target_engine_id 2 snmp _target_mib 145 snmp add_agent_caps 2 101 c 1 101 c 2 101 change_log_size 1 102 config 0 102 current_address 0 103 current_community 0 103 current_context 0 103 current_net_if_data 0 103 current_request_id o 103 date_and_time 0 104 date_and_time_to_string 1 104 date_and_time_to_universal_time 1 104 debug 2 104 del_agent_caps 1 104 enum_to_int 2 104 enum_to_int 3 105 get 2 105 get_agent_caps 0 105 get_symbolic_store_db 0 105 info 1 106 int_to_enum 2 106 int_to_enum 3 106 is_consistent 1 106 load_mibs 2 106 local_time_to_date_and_time 1 107 log_to_txt 2 107 log_to_txt 3 107 log_to_txt 4 107 log_to_txt 5 107 log_to_txt 6 107 log_to_txt 7 107 mib_to_hr1 1 108 name_to_oid 1 108 Simple N etwork M anagement Protocol SN M P 155 Index of Modules and Functions name_to_oid 2 108 oid_to_name 1 108 oid_to_name 2 108 register_subagent 3 108 send_notification 3 109 send_notification 4 109 send
82. _mod see configuration parameters page 27 Also added a size limit to the snmp_error module M essages larger then 1024 chars will be truncated Added a very simple error report module snmp_error_io which writes the message to stdout using the io module without any limitations Own Id OTP 4279 Aux Id Seq 7309 Test manager does not send error message in quiet mode If the request to the manager contains an erroneous oid no information is sent back to the client that started the manager See quiet config parameter page 132 for the new reply value Added two new functions for oid to from aliasname conversion to be used by the test manager users see oid_to_name page 131 and name_to_oid page 131 Own Id OTP 4250 Aux Id Seq 7270 Simple N etwork M anagement Protocol SN M P 69 Chapter 1 SNMP User s Guide Reported Fixed Bugs and Malfunctions e Handling of large erroneous SN MP messages corrected Encoding of the reply to these messages failed due to a bug in the length encoding Also corrected counter increments Own Id OTP 4278 Aux Id Seg 7309 1 13 5 SNMP Development Toolkit v3 3 4 Version 3 3 4 supports code replacement in runtime from to version 3 3 3 3 3 2 3 3 1 3 3 0 and 3 2 2 with the exception of what s mentioned in the version 3 3 0 note Improvements and new features Reported Fixed Bugs and Malfunctions e Crypto keys changed from string to list Own Id OTP 4206 Aux Id Seg 7207 e SNMP date
83. _notification 5 109 send_notification 6 109 send_trap 3 110 send_trap 4 110 universal_time_to_date_and_time 1 111 unload_mibs 2 111 unregister_subagent 2 112 validate_date_and_time i 112 verbosity 2 112 snmp_community_mib configure 1 113 reconfigure 1 113 snmp error config_err 2 114 user_err 2 114 snmp error_io config_err 2 115 user_err 2 115 snmp_error_report config_err 2 116 user_err 2 116 snmp framework_mib configure 1 117 init o 117 snmp generic get_index_types 1 119 get_status_col 2 119 table_func 2 119 table_func 4 119 table_get_elements 3 120 table_next 2 120 table_row_exists 2 120 table_set_elements 3 120 variable_func 2 120 variable_func 3 120 variable_get 1 120 variable_set 2 120 snmp _index delete 1 123 delete 2 124 get 2 124 get_last 1 124 get_next 2 124 insert 3 124 key_to_oid 2 124 new 1 125 snmp_local_db dump 0 127 match 2 127 print 0 127 print 1 127 print 2 127 register_notify_client 2 128 table_create 1 127 table_create_row 3 127 table_delete 1 128 table_delete_row 2 128 table_exists 1 128 table_get_row 2 128 unregister_notify_client 1 128 snmp_mgr expect 2 130 expect 3 130 expect 4 130 expect 6 130 g 1 130 gb 3 130 gn 0 131 gn 1 131 name_to_oid 1 131 oid_to_name 1 131 r o 131 s 1 131 start 1 131 start_link 1 132 stop 0 133 snmp_mpd discarded_pdu 1 135 generate_msg 4 135 generate_response_msg 4 134
84. a default and making the conceptual row available for use by the managed device Interaction 1 Selecting an Instance Identifier The algorithm used to select an instance identifier varies for each conceptual row In some cases the instance identifier is semantically significant e g the destination address of a route and a management station selects the instance identifier according to the semantics In other cases the instance identifier is used solely to distinguish conceptual rows and a management station without specific knowledge of the conceptual row might examine the instances present in order to determine an unused instance identifier This approach may be used but it is often highly sub optimal however it is also a questionable practice for a naive management station to attempt conceptual row creation Alternately the MIB module which defines the conceptual row might provide one or more objects which provide assistance in determining an unused instance identifier For example if the conceptual row is indexed by an integer value then an object having an integer valued SYNTAX clause might be defined for such a purpose allowing a management station to 62 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B issue a management protocol retrieval operation In order to avoid unnecessary collisions between competing management stations adjacent retrievals of this object should be different
85. a new Net if process The name of the N et if module is passed as a start argument to the snmp_agent Process Function Module start_link MasterAgent Args Arguments MasterAgent gt isa Pid Args is aa list of arguments e net_if_verbosity silence info log debug trace A description of verbosity can be found here page 112 and here page 30 e net_if_recbuf integer The size to be used for the UDP receive buffer Return values The return values are e ok Pid where Pid is a linked Pid of the N et if process e error Reason if the operation fails 1 10 2 Messages The section M essages describes mandatory messages which N et if must send and be able to receive Outgoing Messages N et if must send the following message when it receives an SNMP PDU from the network that is aimed for the M asterA gent MasterAgent snmp_pdu Vsn Pdu PduMS ACMData From Extra Vsn is either version 1 version 2 Or version 3 Pdu isan SNMP PDU record as defined in snmp_types hri1 with the SNMP request PduMs is the M aximum Size of the response Pdu allowed Normally this is returned from snmp_mpd process_packet see Reference M anual e ACMData is data used by the Access Control Module in use Normally this is returned from snmp_mpd process_packet see Reference M anual From is the source address If U D P over IP is used this should be a 2 tuple IP UDPport where IP isa 4 tuple with the
86. above behave exactly as shown but they are free to perform other actions For example a get request may have side effects such as setting some other variable perhaps a global lastAccessed variable Simple N etwork M anagement Protocol SN M P 21 Chapter 1 SNMP User s Guide 1 3 2 Using the ExtraArgument The ListOfExtraArguments can be used to write generic functions This list is appended to the standard arguments for each function Consider two read only variables for a device ipAdr and name with object identifiers 1 1 23 4 and 1 1 7 respectively To access these variables one could implement the two Erlang functions ip_access and name_access Which will be in the MIB The functions could be specified in a text file as follows ipAdr my_module ip_access Or using the oid syntax for name 1 1 1 7 1 my_module name_access The ExtraArgument parameter is the empty list For example when the agent receives a get request for the ipAdr variable a call will be made to ip_access get The value returned by this function is the answer to the get request If ip_access and name_access are implemented similarly we could write a generic_access function using the ListOfExtraArguments ipAdr my_module generic_access IPADR The mnemonic name is more convenient than 1 1 7 name my_module generic_access NAME W hen the agent receives the same get request as above a call will be mad
87. active set status noError gt D inconsist inconsistent inconsistent column to or entValue Value Value createAndGo linconsistent Value set status noError see 1 inconsist inconsistent inconsistent column to or entValue Value Value createAndWait wrongValue set status linconsistent linconsist noError noError column to Value entValue active or lsee 2 gt DI gt D gt D set status linconsistent linconsist noError InoError gt C column to Value entValue notInService or or lsee 3 gt C gt C wrongValue set status noError noError noError noError column to destroy gt A gt A gt A gt A set any other see 4 noError noError lsee 5 column to some value see 1 gt C gt D 1 goto B or C depending on information available to the agent 2 if other variable bindings included in the same PDU
88. ail logging and the consideration of distributed tables Chapter 8 Definition of Configuration Files is a reference chapter which contains more detailed information about the configuration files Chapter 9 Definition of Instrumentation Functions is a reference chapter which contains more detailed information about the instrumentation functions Chapter 10 Definition of Net if is a reference chapter which describes the N et if function in detail Appendix A describes the conversion of SN MPv2 to SNM Pv1 error messages Appendix B contains the RFC1903 text on RowStatus 1 1 4 Where to Find More Information Refer to the following documentation for more information about SN MP and about the Erlang O TP development system Marshall T Rose 1991 The Simple Book An Introduction to Internet M anagement Prentice H all Evan McGinnis and David Perkins 1997 Understanding SN MP MIBs Prentice H all RFC1155 1157 1212 and 1215 SNM Pv1 RFC 1901 1907 SNM Pv2c RFC 1908 2089 coexistence between SN M Pv1 and SN M Pv2 RFC 2271 RFC2273 SNMP std MIBs the M nesia U ser s Guide the Erlang 4 4 Extensions User s Guide the Reference M anual the Erlang Embedded Systems U ser s Guide the System Architecture Support Libraries SASL User s Guide the Installation Guide the Asn1 User s Guide Concurrent Programming in Erlang 2nd Edition 1996 Prentice Hall ISBN 0 13 508301 X Simple N e
89. ame file several times Own Id OTP 1425 e The agent could under som circumstances crash when a table instrumentation function crashed Own Id OTP 1738 Aux Id seq351 Incompatibilities with v1 3 1 e TheMIBs must be recompiled e The MIB compiler is more strict N ow it also checks that macros are imported correctly e The Netlf API is entirely re written It is now easier to implement a N etlf process e The Proxy handling in snmp_net_if is removed e The INTERNAL MIB has changed its name to OTP SN M PEA M IB Known bugs and problems The User s Guide now describes where the Agent and MIB compiler don t implement the standard 1 13 30 SNMP Development Toolkit v1 3 1 Reported Fixed Bugs and Malfunctions e When trying to create a row that already exists in snmp_local_db the new row is inserted instead of the old row 1 13 31 SNMP Development Toolkit v1 3 Improvements and new features e The MIB compiler has a new include_lib like option called i1 Own Id OTP 1041 The RFC1213 MIB STANDARD MIB and INTERNAL MIB are delivered in compiled form bin as well as source form The compiled mibs are located in snmp 1 2 3 priv mibs directory Use the option il to the mib compiler to find these files Own Id OTP 1272 A new module snmp_index for building snmp indexes like the one used by M nesia is added O wn Id OTP 1307 snmp mib_to_hr1 generates OBJECT IDENTIFIERsfor all internal nodes in a MIB module not just for
90. and DateAndTime These data types are originally defined as textual conventions in SNM Pv2 TC RFC 1903 SNMP FRAMEWORK MIB and SNMP MPD MIB TheSNMP FRAMEWORK MIB and SN MP M PD M IB define additional read only managed objects which is used in the generic SN MP framework defined in RFC 2271 and the generic message processing and dispatching module defined in RFC 2272 They are generic in the sense that they are not tied to any specific SN MP version The objects in these M IBs are implemented in the modules snmp_framework_mib and snmp_standard_mib respectively All objects reside in volatile memory and the configuration files are always reread at startup If SN M Pv3 is used these MIBs are loaded by default SNMP TARGET MIB and SNMP NOTIFICATION MIB TheSNMP TARGET MIB and SNMP NOTIFICATION MIB define managed objects for configuration of notification receivers They are described in detail in RFC 2273 Only a brief description is given here TheSNMP NOTIFICATION MIB is implemented according to snmpNotifyBasicCompliance It means the notification filtering is not implemented All tables in these M IBs have a column of type StorageType The value of this column specifies how each row is stored and what happens in case of a restart of the agent The implementation supports the values volatile and nonVolatile When the tables are initially filled with data from the configuration files these rows will automatically have storage type nonVo
91. applications must be dynamic as well For example if we have an equipment MIB for a rack and different M IBs for boards which can be installed in the rack the MIB for a card should be loaded when the card is inserted and unloaded when the card is removed In this agent system there are two ways to dynamically install management information The most common way is to load an MIB into an agent The other way is to use a subagent which is controlled by the application and is able to register and de register itself A subagent can register itself for maniging a sub tree not to be mixed up with erlang register The sub tree is identified by an O bject Identifier W hen a subagent is registered it receives all requests for this particular sub tree and it is responsible for answering them It should also be noted that a subagent can be started and stopped at any time Compared to other SNMP agent packages there is a significant difference in this way of using subagents O ther packages normally use subagents to load and unload MIBsin runtime In Erlang it is easy to load code in runtime and it is possible to load an MIB into an existing subagent It is not necessary to create a new process for handling anew MIB Subagents are used for the following reasons e to provide a more complex set transaction scheme than master agent e to avoid unnecessary process communication e to provide a more lightweight mechanism for loading and unloading MIBs in r
92. be used to add an AGENT CAPABILITY statement to the sysO RTable in the agent The table is defined in the SN M Pv2 M IB c File c File Options gt ok BinFileName error Reason Types e File string e Options opt e opt db volatile persistent mnesia fi dir 1 il dir 1 outdir dir warnings bool group_check bool deprecated bool description bool verbosity silence warning info log debug trace e dir string e BinFileN ame string Compiles the specified M IB file lt File gt mib The compiled file BinFileName is called lt File gt bin Simple N etwork M anagement Protocol SN M P 101 snmp SNMP Reference Manual The option db specifies which database should be used for the default instrumentation Default is volatile The option i specifies the path to search for imported compiled M IB files The directories should be strings with a trailing directory delimiter Default is The option i1 include_lib also specifies a list of directories to search for imported MIBs It assumes that the first element in the directory name corresponds to an OTP application The compiler will find the current installed version For example the value samp mibs will be replaced by snmp 3 1 1 mibs or what the current version may be in the system The current directory and the lt snmp home gt priv mibs are always listed last in the include path
93. c Varbinds page 130 Test if the manager has received a response trap inform or report expect Id v2trap Varbinds page 130 Test if the manager has received a response trap inform or report expect Id report Varbinds page 130 Test if the manager has received a response trap inform or report expect Id inform InformReply Varbinds page 130 Test if the manager has received a response trap inform or report g Oids gt void page 130 Send a get request gb NonRepeaters MaxRepetitions Oids gt void page 130 Send a get bulk request gn Oids gt void page 131 Send a get next request gn gt void page 131 Send a get next request gn N gt void page 131 Send N get next request requests r gt voidQ page 131 Resend the last request oid_to_name 0id gt ok Name error Reason page 131 Transform a oid to it s aliasname name_to_oid Name gt ok Oid error Reason page 131 Transform a aliasname to it s oid s Varbinds gt void page 131 Send a set request start Options page 131 Start the SN MP manager start_link Options gt void page 132 Start the SN M P manager stop gt void page 133 Stop the SN M P manager Simple N etwork M anagement Protocol SN M P 95 96 SNMP Reference Manual snmp_mpd The following functions are exported e init mpd Options gt mpd_state page 134 Initialize the MPD module e
94. ch are use internally and are not seen by SN MP Still the data model from SNMP must be maintained Although this is undesirable it is a pragmatic compromise in many situations where simple and efficient implementation is preferable to abstraction 42 Simple N etwork M anagement Protocol SN M P 1 7 Advanced Topics Creating the Mnesia Table The table must be created in M nesia before the manager can use it The table must be declared as type snmp This makes the table ordered in accordance with the lexicographical ordering rules of SNMP The name of the M nesia table must be identical to the SN MP table name The types of the INDEX fields in the corresponding SN MP table must be specified If the SNMP table has more than one INDEX column the corresponding M nesia row is a tuple where the first element is a tuple with the INDEX columns Generally if the SN MP table hasN INDEX columns and C data columns the M nesia table is of arity C N 1 where the key is a tuple of arity N if N gt 1 orasingletermifN 1 Refer to the M nesia User s Guide for information on how to declare a M nesia table as an SN MP table The following example illustrates a situation in which we have an SN MP table that we wish to implement as a M nesia table The table stores information about employees at a company Each employee is indexed with the department number and the name empTable OBJECT TYPE SYNTAX SEQUENCE OF EmpEntry ACCESS not accessible STAT
95. conf and notify conf The old file trap_dest conf is not used However if atrap_dest conf file exists the agent automatically converts that file to the new files e The function snmp send_trap no longer takes a CommunityString as a parameter This parameter is now optional and refers to the snmpNotifyName in snmpNotifyTable Old code that uses the old function does not have to be changed e There are two new messages a net if process must handle These are messages to handle Inform Requests Future Improvements M ore M IBs from the so called SN M Pv3 effort will be implemented as these mibs become standards although these M IBs don t require SN M Pv3 This means that more tables from OTP SNMPEA MIB become obsolete eg intCommunityTable intAddressTable and intViewTable SN M Pv3 itself will be implemented 1 13 26 SNMP Development Toolkit v2 1 1 Reported Fixed Bugs and Malfunctions e The snmp_note_store server sometimes didn t invoked its gc which meant that its internal data structure could grow very large Own Id OTP 1946 OT P 2004 Aux Id seq451 e f a possibly user defined net if process crahses and restarts the agent could crash as well Own Id OTP 2017 Simple N etwork M anagement Protocol SN M P 81 Chapter 1 SNMP User s Guide e Failover takeover of the SN MP agent administering the MIB did not work since the old implementation tried to delete a M nesia table on a node which was not up and running
96. destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is usm conf reconfigure ConfDir gt void Types e ConfDir string Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configuration file will have StorageType nonVolatile Thus the data in the SN MP USER BASED SM M IB after this function has been called is the data from the configuration files All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is usm conf 146 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _view_based_acm_mib snmp_view_based_acm_mib Erlang M odule The module snmp view_based_acm_mib implements the instrumentation fu
97. determines which of the new values is going to be supplied 40 Simple N etwork M anagement Protocol SN M P 1 7 Advanced Topics W hen the agent receives a request it keeps the request ID for one second after the response is sent If the agent receives another request with the same request ID during this time from the same IP address and UDP port that request will be discarded This mechanism has nothing to do with the function snmp current_request_id 0 1 7 3 Subagents and Dependencies The toolkit supportsthe use of different types of subagents but not the construction of subagents Also the toolkit does not support dependencies between subagents A subagent should by definition be stand alone and it is therefore not good design to create dependencies between them 1 7 4 Distributed Tables A common situation in more complex systems is that the data in a table is distributed Different table rows are implemented in different places Some SN MP toolkits dedicate an SN MP subagent for each part of the table and load the corresponding M IB into all subagents The M aster A gent is responsible for presenting the distributed table as a single table to the manager The toolkit supplied uses a different method The method used to implement distributed tables with this SNMP tool isto implement a table coordinator process responsible for coordinating the processes which hold the table data and they are called table holders All table holders
98. ding the material in the SN MP User s Guide e the basics of the Simple N etwork M anagement Protocol version 1 SN M Pv1 e the basics of the community based Simple N etwork M anagement Protocol version 2 SN M Pv2c e the basics of the Simple N etwork M anagement Protocol version 3 SN M Pv3 e the knowledge of defining M IBs using SM Iv1 and SM lv2 e familiarity with the Erlang system and Erlang programming The tool requires Erlang release 4 7 or later Simple N etwork M anagement Protocol SN M P 1 Chapter 1 SNMP User s Guide 1 1 3 About This Manual In addition to this introductory chapter the SN MP User s Guide contains the following chapters Chapter 2 Functional D escription describes the features and operation of the SN MP development toolkit It includes topics on Subagents and M IB loading Internal MIBs and Traps Chapter 3 Instrumentation Functions describes how instrumentation functions should be defined in Erlang for the different operations Chapter 4 The MIB Compiler describes the features and the operation of the MIB compiler Chapter 5 Running the A gent describes how to start and configure the agent Topics on how to debug the agent are also included Chapter 6 Implementation Example describes how an MIB can be implemented with the SN MP Development Toolkit Implementation examples are included Chapter 7 Advanced Topics describes subagents agent semantics audit tr
99. distributed Erlang application it will during takeover try to load the same M IBs that were loaded at the old node It uses the same filenames as the old node If the M IBs are not located in the same paths at the different nodes the MIBs must be loaded explicitly after takeover 1 7 6 Using Mnesia Tables as SNMP Tables The M nesia DBM S can be used for storing data of SN MP tables This means that an SN MP table can be implemented as a M nesia table and that a M nesia table can be made visible via SN MP This mapping is largely automated There are three main reasons for using this mapping e We get all features of M nesia such as fault tolerance persistent data storage replication and so on e Much of the work involved is automated This includes get next processing and RowStatus handling e The table may be used as an ordinary M nesia table using the M nesia API internally in the application at the same time as it is visible through SN MP When this mapping is used insertion and deletion in the original M nesia table is slower with a factor O log n The read access is not affected A drawback with implementing an SN MP table as a M nesia table is that the internal resource is forced to use the table definition from the MIB which means that the external data model must be used internally Actually this is only partially true The M nesia table may extend the SNMP table which means that the M nesia table may have columns whi
100. dit the files manually or run the configuration tool as follows If authentication or encryption is used SN M Pv3 only start the crypto application 1 gt application start crypto ok 2 gt snmp config 28 Simple N etwork M anagement Protocol SN M P 1 5 Running the Agent Simple SNMP configuration tool v3 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 System name sysName standard variable mbj s agent Engine ID snmpEngineID standard variable mbj s engine The UDP port the agent listens to standard 161 4000 IP address for the agent only used as id when sending traps dront ericsson se 5 IP address for the manager only this manager will have access to the agent traps are sent to this one dront ericsson se 6 To what UDP port at the manager should traps be sent standard 162 5000 7 What SNMP version should be used 1 2 3 1 amp 2 1 amp 2 3 2 3 3 7b Should notifications be sent as traps or informs trap 8 Do you want a none minimum or semi secure configuration Note that if you chose vi or v2 you will not get any security for these requests none minimum semi minimum 8b Give a password of at least length 8 It is used to generate private keys for the configuration secretpasswd 9 Where is the configuration directory absolute home mbj snmp_conf 10 Current configuration files will now be
101. e snmp_priority atom lt optional gt Defines the Erlang priority for all SN MP processes Default is normal vi bool lt optional gt Defines if the agent shall speak SNM Pv1 Default is true v2 bool lt optional gt Defines if the agent shall speak SN M Pv2c Default is true v3 bool lt optional gt Defines if the agent shall speak SN MPv3 Default is true snmp_local_db_auto_repair false true true_verbose lt optional gt When starting snmp_local_db it always tries to open an existing database If false and some errors occur anew datebase is created instead If true erroneous transactions in the logfile are ignored If true_verbose erroneous transactions in the logfile are igored and an error message is written D efault is true snmp mibentry_override bool lt optional gt If this value is false then when loading a mib each mib entry is checked prior to installation of the mib The perpose of the check is to prevent that the same symbolic mibentry name is used for in different oid s Default is false snmp_trapentry_override bool lt optional gt If this value is false then when loading a mib each trap is checked prior to installation of the mib The perpose of the check is to prevent that the same symbolic trap name is used for in different trap s Default is false snmp_error_report mod atom lt optional gt Defines an error report module other then the default Two modules are provided w
102. e RA ees 1 4 6 Compiling from a Shell or a Makefile o o o o 1 4 7 Deviations from the Standard o o e ees LS Running the A gent ia ariaa a a R a AAA 1 5 1 Configuringthe Agent 0 00 Simple N etwork M anagement Protocol SN M P OVO WOUR KR WWNNP OO eS y 1 6 1 7 1 8 1 9 1 5 2 Modifying the Configuration Files 0 oo 28 1 5 3 StartingtheAgent o o e 29 1 5 4 Debuggingthe Agent o o e 30 Implementation Example 2 31 EOR MIB oe ea A A E OS SE ogra BE ee iS To 31 1 6 2 Default Implementation 2 0 0 00 ce 32 1 6 3 Manual Implementation 0 0 0 0 0 02 eee ee 34 Advanced TOPICS ur OS aes BAe kk eR oe dot ele RA SD 39 1 7 1 When to use a Subagent aoaaa 2 o e o e 39 14 72 Agent Semantics 24 nra aa r A ee ie en ee a aS 40 1 7 3 Subagents and D ependencies o ee 41 1 7 4 Distributed Tables i voor aura 41 1 7 5 iFault Tolerance nena 2 oh bb a cE Le Be ce e ERR 41 1 7 6 Using M nesia Tables as SNMP Tables o o o 42 1 7 7 Audit Trail Logging 2er PSEA e aa 45 1 7 8 Deviations from the Standard e 45 Definition of Configuration Files 2 46 1 8 1 Agent Information s secr a aa Molo eee ee ee a ee ee a 46 1 92 CONE e A cr VEEL TSB thas la ae Bs 47 1 8 3 System Information aaa 47 E84 COMMUNITIES aiea a A A i E Bs 47 1 8 5 MIBViewsforVACM
103. e to generic_access get IPADR Yet another possibility closer to the hardware could be ipAdr my_module generic_access 16 2543 name my_module generic_access 16 A2B3 1 3 3 Default Instrumentation When the MIB definition work is finished there are two major issues left e Implementing the MIB e Implementing a M anager A pplication Implementing an M IB can be a tedious task M ost probably there is a need to test the agent before all tables and variables are implemented In this case the default instrumentation functions are useful The toolkit can generate default instrumentation functions for variables as well as for tables Consequently a running prototype agent which can handle set get get next and table operations is generated without any programming The agent stores the values in an internal volatile database which is based on the standard module ets H owever it is possible to let the MIB compiler generate functions which use an internal persistent database or the Mnesia DBMS Refer to the M nesia User Guide and the Reference M anual section SNMP module snmp_generic for more information When parts of the MIB are implemented you recompile it and continue on by using default functions With this approach the SNMP agent can be developed incrementally The default instrumentation allows the application on the manager side to be developed and tested simultaneously with the agent As soon as
104. e_lib snmp include SNMPv2 MIB hr1 The initial values for the managed objects defined in these tables are read at startup from a set of configuration files These are described in Configuration Files page 27 STANDARD MIB and SNMPv2 MIB These MIBs contain the snmp and system groups from M IB II which is defined in RFC 1213 STANDARD MIB or RFC1907 SN M Pv2 M IB They are implemented in the snmp_standard_mib module The snmp counters all reside in volatile memory and the system and snmpEnableAuthenTraps variables in persistent memory using the SNMP built in database refer to the Reference M anual section snmp module snmp_local_db for more details If another implementation of any of these variables is needed e g to store the persistent variables in a M nesia database an own implementation of the variables must be made That MIB will be compiled and loaded instead of the default MIB The new compiled MIB must have the same name as the original MIB i e STANDARD MIB or SNM Pv2 M IB and be located in the SNMP configuration directory see Configuration Files page 27 O ne of these M IBs is always loaded If only SNM Pv1 is used STANDARD MIB is loaded otherwise SN M Pv2 M IB is loaded 10 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description Data Types There are some new data types in SN M Pv2 that are useful in SN M Pv1 as well In the STANDARD MIB three data types are defined RowStatus TruthValue
105. econd problem occurs if the database is large dumping the entire database may take some considerable time and it may slow down the system e The third problem is that insertions and deletions are inefficient for large tables All these problems are best solved by using M nesia instead In order to know when the content of the database should be dumped it is possible to register unregister a notification client This client will be notified of all persistent permanent changes to the database by a call to Module notify Client What W here the arguments are e Client term e What insert delete close N ote The snmp local db does not initiate the dump Instead this could be initiated by the notify client as a result of the received db change information See register_notify_client 2 and unregister_notify_client 2 below for further information The following functions describe the interface to snmp_local_db Each function has a M nesia equivalent The argument NameDb is a tuple Name Db where Name is the 126 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_local_db symbolic name of the managed object as defined in the MIB and Db is either volatile or persistent mnesia is not possible since all these functions are snmp_local_db specific Common Data Types In the functions defined below the following types are used e NameDb Name Db e Name atom Db volatile pers
106. ed by ESC TAB The function can be used on arunning system or by copying the entire log directory and calling this function SNMP must be running in order to provide M IB information LogDir is the name of the directory where the audit trail log is stored Mibs is a list of M ibs to be used The function uses the information in the Mibs to convert for example object identifiers to their symbolic name OutFile is the name of the generated textfile It defaults to snmp_log txt LogName is the name of the log default is snmp log LogFile is the name of the log file default is snmp log Start is the start first date and time from which log events will be converted and Stop is the stop last date and time to which log events will be converted The format of an audit trail log text item is as follows Tag Addr Community TimeStamp Vsn PDU where Tag iS request response report trap Or inform Addr is IP Port or comma space separated list of such Community is the community parameter SN MP version v1 and v2 or SecLevel AuthEngineID UserName SNMP v3 TimeStamp is a date and time stamp and Vsn is the SNMP version PDU is a textual version of the protocol data unit There is a new line between Vsn and PDU Simple N etwork M anagement Protocol SN M P 107 snmp SNMP Reference Manual mib_to_hrl MibName gt ok error Reason Types e MibName string Generates a hr1 file with definitions of Erlang constants
107. efore it can be read Use the function snmp log_to_txt 2 3 for this purpose 1 7 8 Deviations from the Standard In some aspects the agent does not implement SN MP fully H ere are the differences e The default functions and snmp_generic cannot handle an object of type NetworkAddress as INDEX SNM Pv1 only Use IpAddress instead e The agent does not check complex ranges specified for INTEGER objects In these cases it just checks that the value lies within the minimum and maximum values specified For example if the range is specified as1 10 12 20 the agent would let 11 through but not 0 or 21 The instrumentation functions must check the complex ranges itself e The agent will never generate the wrongEncoding error If a variable binding is erroneous encoded the asniParseError counter will be incremented e A tooBig error in an SNM Pv1 packet will always use the NULL value in all variable bindings Simple N etwork M anagement Protocol SN M P 45 Chapter 1 SNMP User s Guide e The default functions and snmp_generic do not check the range of each OCTET in textual conventions derived from OCTET STRING eg DisplayString and DateAndTime This must be checked in an overloaded is_set_ok function 1 8 Definition of Configuration Files All configuration data must be included in configuration files that are located in the configuration directory The name of this directory is given in the snmp_config dir configuration paramet
108. eives a discarded_pdu message from the agent Simple N etwork M anagement Protocol SN M P 135 snmp _notification_mib SNMP Reference Manual snmp_notification_mib Erlang Module The module snmp_notification mib implements the instrumentation functions for the SNM P NOTIFICATION MIB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is notify conf reconfigure ConfDir gt void Types e ConfDir string Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configuration file will have StorageType nonVolatile Thus the data in the SNM P NOTIFICATION M IB after this function has been called isfrom the configuration files If an error
109. er These files are read at start up and are used to initialize the SN M Pv2 MIB or STANDARD M IB SNM P FRAMEWORK MIB SNM P MPD MIB SNM P VIEW BASED ACM MIB SNMP COMMUNITY MIB SNM P USER BASED SM M IB SNM P TARGET MIB and SNM P NOTIFICATION M IB refer to the Management of the A gent page 9 for a description of the MIBs The directory where the configuration files are found is given as a parameter to the agent The entry format in all files are Erlang terms separated by a and a newline In the following sections the formats of these terms are described Comments may be specified as ordinary Erlang comments Syntax errors in these files are discovered and reported with the function config_err 2 of the error report module at start up 1 8 1 Agent Information The agent information should be stored in a file called agent conf Each entry is a tuple of size two AgentVariable Value e AgentVariable is one of the variables is SNM P FRAMEWORK MIB or one of the internal variables intAgentUDPPort which defines which UDP port the agent listens to or intAgentIpAddress which defines the IP address of the agent e Value is the value for the variable The following example shows a agent conf file intAgentUDPPort 4000 intAgentIpAddress 141 213 11 24 snmpEngineID mbj s engine peng J 8 snmpEngineMaxPacketSize 484 The value of snmpEnginelD is a string which for a deployed agent should have a very
110. error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is vacm conf Simple N etwork M anagement Protocol SN M P 147 snmp_view_based_acm_mib SNMP Reference Manual 148 Simple N etwork M anagement Protocol SN M P List of Figures 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 1 9 MIB Compiler Principles o o 6 Starting the Agent os ii a A A A ERROR 6 AfChitectUre ua a E AA es ee 7 Overview of the mechanism of MIB selection o o ee es 12 Contents OR mystable ii a e e e e ea re Ga de a 19 GetNextfrom 3 1 1 and 5 1 1 o o e 20 G etN ext from 3 2 1 and 5 2 1 o o e 20 GetNext from 3 1 2 and 4 1 2 o o e 21 ThePurposeofNetif o o o e 55 Simple N etwork M anagement Protocol SN M P 149 List of Figures 150 Simple N etwork M anagement Protocol SN M P List of Tables LEL Emor Messages s es Ey ikina ld o ee a a AA ie ge EH A ea 59 Simple N etwork M anagement Protocol SN M P 151 List of Tables 152 Simple N etwork M anagement Protocol SN M P Index of Modules and Functions M odules are typed in this way Functions are typed in this way add_agent_caps 2 snmp 101 c 1 snmp 101 c 2 snmp 101 change_log_size 1 snmp 102 config 0 snmp 102 config_err 2 snmp error 114 snm
111. error occurs at runtime for example if a user defined instrumentation function returns erroneous Format and Args are asin io format Format Args Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp framework_mib snmp_framework_mib Erlang Module The module snmp framework_mib implements instrumentation functions for the SN M P FRAMEWORK MIB and functions for initializing and configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old data Thus the data in the SN MP FRAMEWORK MIB after this function has been called is from the configuration files All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is context conf init gt void This function is called from the supervisor at system start up Creates the necessary objects in the database if they do not exist It does not destroy any old values Simple N etwork M anagement Protocol SN M P 117 snmp _generic SNMP
112. ersion 3 1 4 3 1 3 and 3 0 9 2 N ote When importing MIBs ensure that the imported M IBs as well as the importing MIB are compiled using the same version of the SN M P compiler The required interface of the N et if module has changed page 56 Improvements and new features e Debugging has been improved It is now possible to debug all named processes individually of the snmp application See the snmp module for details e Filter audit trail logs on timestamp Own Id OT P 3600 e The MIB compilator has been improved It is possible to include D escription field into compiled MIB Own Id OTP 3538 Reported Fixed Bugs and Malfunctions e Failure converting audit trace log to text file Own Id OTP 3649 OT P 3650 Aux Id seq4844 Simple N etwork M anagement Protocol SN M P 73 Chapter 1 SNMP User s Guide 1 13 13 SNMP Development Toolkit v3 1 4 Version 3 1 4 supports code replacement in runtime from to version 3 1 3 Improvements and new features Debugging has been improved It is now possible to debug all named processes individually of the snmp application See the snmp module for details Reported Fixed Bugs and Malfunctions Erroneous check for duplicate trap mib entries A check for duplicate mibentries has been added This check can be overridden with the sys config tuple snmp_mibentry_override bool The check for duplicate trap entries was erroneous only the first trapentry in a mib was chec
113. essary when in fact the agent will not allow that particular columnar instance to be created or written In this case the management protocol set operation will fail with an error such as noCreation or notWritable In this case the management station decides whether it needs 64 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B to be able to set a value for that particular columnar instance If not the management station re issues the management protocol set operation but without setting a value for that particular columnar instance otherwise the management station aborts the row creation algorithm Interaction 2b Negotiating the Creation of the Conceptual Row The management station issues a management protocol set operation which sets the desired instance of the status column to createAndWait If the agent is unwilling to process a request of this sort the set operation fails with an error of wrongValue As a consequence such an agent must be prepared to accept a single management protocol set operation i e interaction 2a above containing all of the columns indicated by its column requirements Otherwise the conceptual row is created a noError response is returned and the status column is immediately set to either notInService or notReady depending on whether it has sufficient information to make the conceptual row available for use by the managed device
114. finitions are detected Own Id OTP 2832 Simple N etwork M anagement Protocol SN M P 79 Chapter 1 SNMP User s Guide 1 13 24 SNMP Development Toolkit v2 2 1 Reported Fixed Bugs and Malfunctions The example mib EX 1 M IB in the user s guide compiles Own Id OTP 2576 Aux Id seq933 The supervisor of the mibs has a correct shutdown time infinity instead of 2 secs Own Id OTP 2606 Aux Id seq947 The automatic conversion of trap_dest conf to the new notify conf target_addres conf and target_params conf now gives an error message if the conversion fails Own Id OTP 2647 The UDP port used by the agent is now opened with the flag reuseaddr set to true Own Id OTP 2655 authenticationFailure are now sent correctly Own Id OTP 2690 A get operation that refers to a not accessible object now returns the correct error code Own Id OTP 2691 The counter snmpInTotalsetVars is now updated properly Own Id OTP 2694 1 13 25 SNMP Development Toolkit v2 2 Improvements and new features 80 The agent and snmp_mgr support Inform R equests when sending SN M Pv2 notifications as defined in rfc2273 This means that it is now possible to send a notification and have the agent wait for an acknowledgement from the manager See the User s guide N otification Sending for a description of the mechanism The agent uses the SN MP NOTIFICATION MIB and SNMP TARGET MIB from rfc2273 to select notification destinations instead of
115. functions e return values from the MIB Simple N etwork M anagement Protocol SN M P 41 Chapter 1 SNMP User s Guide The agent is highly fault tolerant If the manager gets an unexpected response from the agent it is possible that some instrumentation function has returned an erroneous value The agent will not crash even if the instrumentation does It should be noted that if an instrumentation function enters an infinite loop the agent will also be blocked forever The supervisor or the application specifies how to restart the agent Using the SNMP Agent in a Distributed Environment The normal way to use the agent in a distributed environment is to use one master agent located at one node and zero or more subagents located on other nodes H owever this configuration makes the master agent node a single point of failure If that node goes down the agent will not work One solution to this problem is to make the snmp application a distributed Erlang application and that means the agent may be configured to run on one of several nodes If the node where it runs goes down another node restarts the agent This is called failover When the node starts again it may takeover the application This solution to the problem adds another problem Generally the new node has another IP address than the first one which may cause problems in the communication between the SN M P managers and the agent If the snmp application is configured as a
116. functions in the module snmp for manipulating D ateA ndTime objects didn t handle the year component correctly Specifically the two octets representing the year should be coded in hex NOTE see Incompatibles below O wn ld OTP 3189 Aux Id seq3655 It is now possible to create new rowsin snmpTargetAddrTable in SNMP TARGET MIB The engine id associated with the target is initialized to by default This can be changed by using the new function snmp_target_mib set_target_engine_id 2 Incompatibilities with v3 0 e Applications that uses the D ateA ndTime manipulating functions might need to be rewritten to handle the correct coding of the year component For example a function that prints a DateA ndTime value needs to be changed The new function snmp date_and_time_to_string 1 can be used 1 13 19 SNMP Development Toolkit v3 0 2 Reported Fixed Bugs and Malfunctions e The agent now starts correctly when a Audit Trail Log is used Own Id OTP 3137 Aux Id seq3594 Simple N etwork M anagement Protocol SN M P 77 Chapter 1 SNMP User s Guide 1 13 20 SNMP Development Toolkit v3 0 1 Improvements and new features A new function snmp change_log_size 1 has been added to dynamically change the size of the Audit Trail Log Own Id OTP 2989 Aux Id seq1499 Reported Fixed Bugs and Malfunctions The function snmp get 2 didn t preserve the order of its input variable list The order of the elements in the returned
117. g N etfM odule atom e Name local atom global atom 142 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _supervisor Starts a supervisor for the SN MP agent system The supervisor starts all involved SN MP processes including the master agent Subagents should be started by calling start_subagent 3 DbDir is a string including a trailing directory delimiter which points to the directory where the database files sre stored ConfDir is a string including a trailing directory delimiter which points to the directory where the configuration file is found If the STAN DARD MIB is not specified in the Mibs list it is loaded from the configuration directory i e with the conf files If no NetIfModules is specified the default net if implementation is used snmp_net_if Prio isan Erlang priority All SNMP processes use this priority Default is the same as default in the Erlang runtime system If no Opts is given name local snmp_master_agent is default start_subagent ParentAgent Subtree Mibs gt ok pidQ error Reason Types e ParentA gent pid e SubTree oid e Mibs MibN ame e MibN ame string Starts a subagent on the node where the function is called The snmp_supervisor must be running If the supervisor is not running the function fails with the reason badarg stop_subagent SubAgent gt ok no_such_child Types e SubA gent pid
118. gement Protocol SN M P 1 9 Definition of Instrumentation Functions Valid Return Values e A list with as many elements as the Cols list where each element is the value of the corresponding column Each element can be value Value The Value must be of correct type length and within ranges otherwise genErr is returned in the response PDU If the object is an enumerated integer the symbolic enum value may be used as an atom If the object is of type BITS the return value shall be an integer or a list of bits that are set noValue noSuchName SN M Pv1 noValue noSuchObject noSuchInstance SN M Pv2 e noValue Error If the row does not exist because all columns have noValue Error the single tuple noValue Error can be returned This is a shorthand for a list with all elements noValue Error e genErr Used if an error occured N ote that this should be an internal processing error e g a caused by a programing fault somewhere If some column does not exist use noValue noSuchName or noValue noSuchInstance f get_next RowIndex Cols ExtraArgs The fumction f get_next RowIndex Cols ExtraArgs is called when a get next or a get bulk request refers to the table The RowIndex argument may refer to an existing row or a non existing row or it may be unspecified The Cols list may refer to unaccessible columns or non existing columns For each column in the Cols list the corresponding next
119. gs gt void page 114 Called if a user related error occurs snmp_error_io The following functions are exported e config err Format Args gt void page 115 Called if a configuration error occurs e user_err Format Args gt void page 115 Called if a user related error occurs Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_error_report The following functions are exported e config err Format Args gt void page 116 Called if a configuration error occurs e user_err Format Args gt void page 116 Called if a user related error occurs samp framework_mib The following functions are exported e configure ConfDir gt void page 117 Configure the SN MP FRAMEWORK MIB e initQ gt voidQ page 117 Initialize the SN MP FRAMEWORK MIB snmp _generic The following functions are exported e get_status_col Name Cols page 119 Get the value of the status column from Cols e get_status_col NameDb Cols gt ok StatusVal false page 119 Get the value of the status column from Cols e get_index_types Name page 119 Get the index types of Name e table_func Op1 NameDb page 119 Default instrumentation function for tables e table_func 0p2 RowIndex Cols NameDb gt Ret page 119 Default instrumentation function for tables e table_get_elements NameDb RowIndex Cols gt Values page 120 Get elements in a table row e table_next NameDb Rest0id
120. he agent Used in v3 only Default is agentE ngine context_engine_id string the context engine ID used in v3 requests D efault is the same as engine_id e sec_level noAuthNoPriv authNoPriv authPriv the requested security level Used in v3 only Default is noAuthNoPriv dir stringO the directory where the file usm conf is located This file is only needed if v3 is used The file has the same syntax as the usm conf file for the agent mibs List of filename MIBsto be loaded in the manager Default is no MIBs The MIBs must be compiled receive_type pdu msg defines the format of delivered messages D efault iS pdu quiet incoming responses are not displayed M essages are sent to the Erlang process that started the manager The format of the message depends on the value of receive_type If the value is pdu default the message is snmp_pdu PD U where PDU isa pdu or a trappdu record defined in snmp_types hr1 If the value is msg the message is snmp_msg Msg Ip Udp If the request was issued with an erroneous oid the message is oid_error Reason where Reason is a printable string Default is this option is not present i e all incoming requests are displayed This option must be present when running test suites vilv2 v3 what SNMP version to use Default is v1 recbuf integer defines the size of a UDP socket receive buffer This is important when sending large regusts to
121. ic store database retrieved by a call to get_symbolic_store_db 0 lt c gt lt p gt lt c gt false is returned if the object is not defined in any loaded M IB register_subagent Agent SubTreeQid Subagent gt ok error Reason 108 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp Types e Agent pid atom e SubTree0 id 0id e SubA gent pid Registers a subagent under a subtree of another agent It is easy to make mistakes when registering subagents and this activity should be done carefully For example a strange behaviour would result from the following configuration snmp_agent register_subagent MAPid 1 2 3 4 SA1 snmp_agent register_subagent SA1 1 2 3 SA2 SA2 will not get requests starting with object identifier 1 2 3 since SA1 does not send_notification Agent Notification Receiver send_notification Agent Notification Receiver Varbinds send_notification Agent Notification Receiver NotifyName Varbinds send_notification Agent Notification Receiver NotifyName ContextName Varbinds gt void Types e Agent pid atom e Notification atom e Receiver no _receiver Tag Recv e Tag term Recv pid atom M F A N otifyN ame string ContextN ame string Varbinds Varbind Varbind Variable Value Column RowIndex Value O1D Value Variable atom Column atom OID oid Value term Row Inde
122. iguration file Format and Args are asin io format Format Args user_err Format Args gt void Types e Format string e Args list The function is called if a user related error occurs at runtime for example if a user defined instrumentation function returns erroneous Format and Args are asin io format Format Args Simple N etwork M anagement Protocol SN M P 115 snmp_error_report SNMP Reference Manual snmp_error_report Erlang Module The module snmp_error_report contains two callback functions which are called if an error occurs at different times during agent operation These functions in turn calls the corresponding function in the configured error report module which implements the actual report functionallity Two simple implementation s is provided with the toolkit the modules snmp_error page 114 which still is the default and module snmp error_io page 115 The error report module is configured using the directive snmp_error_report_mod see configuration parameters page 27 Exports config_err Format Args gt void Types e Format string e Args list The function is called if an error occurs during the configuration phase for example if a syntax error is found in a configuration file Format and Args are asin io format Format Args user_err Format Args gt void 116 Types e Format string e Args list The function is called if a user related
123. is is impossible to check for the compiler If a word is a keyword in any of SM Iv1 or SM Iv2 it is a keyword in the compiler deviates from SM Iv1 only Indexes in a table must be objects not types deviates from SM Iv1 only A subset of all semantic checks on types are implemented For example strictly the TimeTicks may not be sub classed but the compiler allows this standard MIBs must pass through the compiler deviates from SM Iv2 only The MIB Object syntax is not implemented since all objects must be unique anyway Two different names cannot define the same OBJECT IDENTIFIER The type checking in the SEQUENCE construct is non strict i e subtypes may be specified The reason for this is that some standard M Bs use this A definition has normally a status field W hen the status field has the value deprecated then the M IB compiler will ignore this definition With the MIB compiler option deprecated true the M IB compiler does not ignore the deprecated definitions An object hasa DESCRIPTIONS field The descriptions field will not be included in the compiled mib by default In order to get the description the mib must be compiled with the option description true Simple N etwork M anagement Protocol SN M P 1 5 Running the Agent 1 5 Running the Agent The chapter Running the A gent describes how the agent is configured and started The topics include e configuration directories and parameters e modifying
124. istent e RowIndex int e Cols Col Col Value Col intQ Value term where RowIndex denotes the last part of the O ID that specifies the index of the row in tha table Cols is alist of column numbers in case of a get operation and a list of column numbers and values in case of a set operation Exports dump gt ok ferror Reason This function can be used to dump the database at any time The entire ets database is dumped to disk and the log file is cleared This might be useful if the log file grows rapidly Returns error Reason if a file system error occured match NameDb Pattern Performs an ets matching on the table See Stdlib documentation module ets for a description of Pattern and the return values print print TableName print TableName Db Types e TableN ame atom Prints the contents of the database on screen This is useful for debugging since the STANDARD MIB and OTP SNMPEA MIB and maybe your own M IBs are stored in snmp_local_db TableName is an atom for a table in the database W hen no name is supplied the whole database is shown table_create NameDb gt bool Creates a table If the table already exist the old copy is destroyed Returns false if the NameDb argument is incorrectly specified true otherwise table_create_row NameDb RowIndex Row gt bool Simple N etwork M anagement Protocol SN M P 127 snmp local_db SNMP Reference Manual Types e
125. ith the toolkit snmp_error and snmp_error_io Default is snmp error snmp_master_agent_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP master agent Default is silence snmp_symbolic_store_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SN MP symbolic store Default is silence snmp_note_store_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP note store Default is silence snmp_net_if_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP net if Default is silence snmp mibserver_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SN MP mib server Default is silence snmp_mib_storage ets dets Dir dets Dir Action mnesia Nodes mnesia Nodes Action lt optior Specifies how info retrieved from the mibs will be stored Default is ets Dir string Dir is the directory where the dets files will be created Nodes node If Nodes then the own node is assumed Action clear keep Default iskeep Action is used to specify what shall be done if the mnesia table already exist 1 5 2 Modifying the Configuration Files To to start the agent the agent configuration files must be modified and there are two ways of doing this Either e
126. jects in these two MIBs An SNM Pv3 agent must implement the SN MP FRAMEWORK MIB and SN M P M PD M IB These M IBs are loaded by default if the agent is configured for SN M Pv3 These M IBs can be loaded for other versions as well There are five other standard MIBs which also may be loaded into the agent These M IBs are e SNMP TARGET MIB and SNM P NOTIFICATION MIB which defines managed objects for configuration of management targets e receivers of notifications traps and informs These M IBs can be used with any SN MP version e SNMP VIEW BASED ACM MIB which defined managed objects for access control This MIB can be used with any SN MP version e SNMP COMMUNITY MIB which defines managed objects for coexistence of SN M Pv1 and SN M Pv2c with SN M Pv3 This MIB is only useful if SNM Pv1 or SN M Pv2c is used possibly in combination with SN M Pv3 e SNM P USER BASED SM M IB which defines managed objects for authentication and privacy This MIB is only useful with SN M Pv3 All of these M IBs should be loaded into the M aster A gent O nce loaded these M IBs are always available in all contexts The ASN 1 code the Erlang source code and the generated hr1 files for them are provided in the distributionand are placed in the directories mibs src and include respectively in the snmp application The hr1 files are generated with snmp mib_to_hr1 1 Include these files in your code asin the following example includ
127. ked This check can now be overridden with the sys config tupple snmp_trapentry_override bool D efault values in both cases are false no override which means the check is made Own Id OTP 3601 Cloning of user from template user failure Own Id OTP 3596 Aux Id seq4584 Problem with deprecated mib definitions A new option for the MIB compilator is used The option is deprecated will get around the problem with deprecated definition Own Id OTP 3574 Aux Id seq4528 Trap sending example in chapter M anual implementation corrected Own Id OTP 3353 1 13 14 SNMP Development Toolkit v3 1 3 Version 3 1 3 supports code replacement in runtime from version 3 1 2 Improvements and new features Reported Fixed Bugs and Malfunctions 74 SN M Pv3 discovery process does not work Own Id OTP 3542 Aux Id seq4449 Corrupt snmp_local_db log files cause snmp crash Changes to the local db is stored on disk in a logfile In atakeover senario the new snmp will try to restore the database by reading the ets table on disk and then update this with the transactions stored in the logfile If the logfile is corrupt this caused a crash Own Id OTP 3537 Aux Id seq4471 Return value genErr from GET instrumentation function treated as not accepted Own Id OTP 3534 Aux Id seq4437 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes snmp date_and_time rewritten to not rely on erlang now Own Id OT
128. key O is a single type as well but if the key_types is a tuple key must be a tuple of the same size In the example above valid keys could be hi mom and no thanks whereas hi hi 42 and hello there would be invalid Warning All API functions that update the index return a NewIndex term This is for backward compatibility with a previous implementation that used a B tree written purely in Erlang for the index The NewIndex return value can now be ignored The return value is now the unchanged table identifier for the ets table The implementation using ets tables introduces a semantic incompatibility with older implementations In those older implementations using pure Erlang terms the index was garbage collected like any other Erlang term and did not have to be deleted when discarded An ets table is deleted only when the process creating it explicitly deletes it or when the creating process terminates A new interface delete 1 is now added to handle the case when a process wants to discard an index table i e to build a completely new Any application using transient snmp indexes has to be modified to handle this Asan snmp adaption usually keeps the index for the whole of the systems lifetime this is rarely a problem Exports delete Index gt true Types e Index N ewlndex index e Key key Simple N etwork M anagement Protocol SN M P 123 snmp _index SNMP Reference Manual D ele
129. l columns in the conceptual row that it wishes to create In response for each column there are three possible outcomes a value is returned indicating that some other management station has already created this conceptual row We return to interaction 1 the exception noSuchInstance is returned indicating that the agent implements the object type associated with this column and that this column in at least one conceptual row would be accessible in the MIB view used by the retrieval were it to exist For those columns to which the agent provides read create access the noSuchInstance exception tells the management Simple N etwork M anagement Protocol SN M P 63 Chapter 1 SNMP User s Guide station that it should supply a value for this column when the conceptual row is to be created the exception noSuchObject is returned indicating that the agent does not implement the object type associated with this column or that there is no conceptual row for which this column would be accessible in the MIB view used by the retrieval As such the management station cannot issue any management protocol set operations to create an instance of this column Once the column requirements have been determined a management protocol set operation is accordingly issued This operation also sets the new instance of the status column to createAndGo When the agent processes the set operation it verifies that it has
130. latile Should the agent restart all nonVolatile rows survive the restart while the volatile rows are lost The configuration files are not read at restart by default These MIBs are not loaded by default snmpNotifyTable An entry in the snmpNotifyTable selects a set of management targets which should receive notifications as well as the type trap or inform of notification that should be sent to each selected management target When an application sends a notification using the function send_notification 5 or the function send_trap the parameter NotifyName specified in the call is used as an index in the table The notification is sent to the management targets selected by that entry snmpTargetAddrTable An entry in the snmpTargetAddrTable defines transport parameters such as IP address and UDP port for each management target Each row in the snmpNotifyTable refers to potentially many rows in the snmpTargetAddrTable Each row in the snmpTargetAddrTable refers to an entry in the snmpTargetParamsTable snmpTargetParamsTable An entry in the snmpTargetParamsTable defines which SN MP version to use and which security parameters to use Which SN MP version to use is implicitly defined by specifying the M essage Processing M odel This version of the agent handles the models v1 v2c and v3 Each row specifies which security model to use along with security level and security parameters Simple N etwork M anagement Protocol SN M P 11
131. les The compiler parses the SM file and associates each table or variable with an instrumentation function see the figure MIB Compiler Principles page 6 The actual instrumentation functions are not needed at MIB compile time only their names The binary output file produced by the compiler is read by the agent at MIB load time see the figure Starting the A gent page 6 The instrumentation is ordinary Erlang code which is loaded explicitly or automatically the first time it is called Instrumentation mymod am sysCFunc get lt code gt Binary file bin sysCFunc set Representation lt code gt Figure 1 2 Starting the A gent 6 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description The SN MP agent system consists of one M aster Agent and optional subagents The M aster A gent can be seen as a special kind of subagent It implements the core agent functionality U D P packet processing type checking access control trap distribution and so on From a user perspective it is used as an ordinary subagent Subagents are only needed if your application requires special support for distribution from the SN MP toolkit A subagent can also be used if the application requires a more complex set transaction scheme than is found in the master agent The following illustration shows how a system can look in runtime _ _Node3_ _ Node 1 l l Po a ete e a om l l Appl l Appl 6 l 1 Appl l l
132. les If the agent is started with the old files it will convert them to the new files N ote however that all information is not available in the old files Thus it is recommended to check the configuration files manually or re generate them using snmp config 0 The module snmp_mpc has changed name to snmp_mpd and it is now documented It should be called only from anet if process 1 13 22 SNMP Development Toolkit v2 2 3 Reported Fixed Bugs and Malfunctions When issuing a GET N EXT request which contains more than one column from a table and the table is empty an erroneus GET RESPONSE was sent to the manager The agent failed to locate the next object for all columns Own Id OTP 2979 1 13 23 SNMP Development Toolkit v2 2 2 Reported Fixed Bugs and Malfunctions The function snmp validate_date_and_time 1 now works for all valid times Own Id OTP 2776 Aux ld seq1238 The MIB compiler now handles D EFVA Ls specified as bit strings e g 10010 b Own ld OTP 2826 Aux ld seq1285 The MIB compiler now handles DEFVALs for Opaque objects Such a DEFVAL must be in string format eg cOfa H Own Id OTP 2827 Aux ld seq1285 The MIB compiler now handles DEFVA Ls with no bits set for BITS objetcs O wn ld OTP 2827 Aux ld seq1285 The MIB compiler gives better error messages when erroneous DEFVA Ls are detected Own Id OTP 2827 Aux Id seq1285 The MIB compiler gives better error messages when erroneous table de
133. loop Own Id OTP 1342 mib_to_hr1 doesn t generate enum definitions for imported OBJECT TYPES Own Id OTP 1355 Traps are not only sent to one manager if several managers are specified as trap destinations but to all of them Own Id OTP 1366 1 13 32 SNMP Development Toolkit v1 2 1 Improvements and new features e The file STANDARD MIB hr1 is now included in the directory snmp include It may de included in source code with include_lib snmp include STANDARD MIB hr1 Own Id OTP 1063 Aux Id HA34986 HA36413 Simple N etwork M anagement Protocol SN M P 85 Chapter 1 SNMP User s Guide Reported Fixed Bugs and Malfunctions Calls to the agent had too short timeout This was most obvious in calls to snmp load mibs 2 Own Id OTP 1078 OTP 1096 Aux Id HA36413 snmp config o tried to validate correct IP addresses resulting in an error when DNS was not used Own Id OTP 1094 snmp mib_to_hr1 1 generated entries for imported OBJECT IDENTIFIERS and imported DEFVALs which could result in macro conflict when hr1 files from more than one MIB was included Own Id OTP 1126 When a row was createAndWaited it wasn t possible to set a row to active in the same request as the rest of the mandatory columns were set Own Id OTP 1128 snmp int_to_enum 2 crashed when called with an Oid without any enums O wn ld OTP 1129 The agent could crash if a RowIndex in a set request was of bad type O wn ld OTP 1131 1 13 33 SNMP
134. lowing functions are exported dump gt ok error Reason page 127 Dump the database to disk match NameDb Pattern page 127 Perform an ets match on the table print page 127 Print the database to screen print TableName page 127 Print the database to screen print TableName Db page 127 Print the database to screen table_create NameDb gt bool page 127 Create a table table_create_row NameDb RowIndex Row gt boo1 page 127 Create a row in a table table_delete NameDb gt void page 128 Delete a table table_delete_row NameDb RowIndex gt bool page 128 D elete the row in the table table_exists NameDb gt bool page 128 Check if a table exists table_get_row NameDb RowIndex gt Row undefined page 128 Get a row from the table Simple N etwork M anagement Protocol SN M P SNMP Reference Manual register_notify_client Client Module gt ok error Reason page 128 Register Client as notification client unregister_notify_client Client gt ok error Reason page 128 Unregister Client as notification client snmp_mgr The following functions are exported expect Id What gt ok error Id Reason page 130 Test if the manager has received a response trap inform or report expect Id ErrorStatus ErrorIndex Varbinds page 130 Test if the manager has received a response trap inform or report expect Id trap Enterp Generic Specifi
135. ly different M IBs can have different set or get mechanisms Process Communication A simple distributed application can be managed without subagents The instrumentation functions can use distributed Erlang to communicate with other parts of the application H owever a subagent can be used on each node if this generates too much unnecessary traffic A subagent processes requests per incoming SN MP request not per variable Therefore the network traffic is minimized If the instrumentation functions communicate with UNIX processes it might be a good idea to use a special subagent This subagent sends the SN MP request to the other process in one packet in order to minimize context switches For example if a whole MIB is implemented on the C level in UNIX but you still want to use the Erlang SN MP tool then you may have one special subagent which sends the variables in the request as a single operation down to C Frequent Loading of MIBs Loading and unloading of M IBs are quite cheap operations H owever if the application does this very often perhaps several times per minute it should load the MIBs once and for all in a subagent This subagent only registers and de registers itself under another agent instead of loading the M IBs each time Thisis cheaper than loading an MIB Interaction With Other SNMP Agent Toolkits If the SNMP agent needs to interact with subagents constructed in another package a special subagent should be used
136. m e Int int Converts the symbolic value Enum to the corresponding integer of the enumerated object or type Name in a MIB The MIB must be loaded Db is a reference to the symbolic store database retrieved by a call to get_symbolic_store_db 0 lt c gt lt p gt lt c gt false is returned if the object or type is not defined in any loaded M IB or if it does not define the symbolic value as enumerated get Agent Vars gt Values error Reason Types e Agent pid atom e Vars oid e Values term e Reason atom oid Performs a GET operation on the agent All loaded MIB objects are visible in this operation The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager That the request specific parameters such as snmp current_request_id 0 are not accessible for the instrumentation functions if this function is used get_agent_caps gt SysORIndex SysORID SysORDescr SysORUpTime Types e SysO RIndex integer e SysO Rid oid e SysO RD escr string e SysO RUpTime integer Returns all AGENT CAPABILITY statements in the sysO RTable in the agent This table is defined in the SN M Pv2 M IB get_symbolic_store_db gt Db Types e Db term Retrieve the symbolic store database reference This is used for faster access to the database using the functions int_to_enum 3 enum_to_int 3 name_to_oid 2 oid_to_name 2 Simple
137. me Cols get_status_col NameDb Cols gt ok StatusVal false Gets the value of the status column from Cols This function can be used in instrumentation functions for is_set_ok undo or set to check if the status column of atable is modified get_index_types Name Gets the index types of Name This function can be used in instrumentation functions to retrieve the index types part of the table info table_func 0p1 NameDb table_func 0p2 RowIndex Cols NameDb gt Ret Types e Opl new delete e Op2 get next is_set_ok set undo This is the default instrumentation function for tables e The new function creates the table if it does not exist but only if the database is the SNMP internal db e The delete function does not delete the table from the database since unloading an MIB does not necessarily mean that the table should be destroyed e The is_set_ok function checks that a row which is to be modified or deleted exists and that a row which is to be created does not exist e The undo function does nothing e The set function checks if it has enough information to make the row change its status from notReady to not InService when a row has been been set to createAndWait If arow isset to createAndWait columns without a value are set to noinit If M nesia is used the set functionality is handled within a transaction Simple N etwork M anagement Protocol SN M P 119 snmp _generic SNMP Reference Manual
138. module and the function fails with the reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is standard conf reinit gt void Resets all snmp counters to 0 sys_up_time gt Time Types e Time int Gets the system up time in hundredth of a second Simple N etwork M anagement Protocol SN M P 141 snmp _supervisor SNMP Reference Manual snmp_supervisor Erlang M odule The snmp_supervisor is the supervisor for the SN MP application There is always one supervisor at each node with an SN MP agent master agent or subagent Exports start_sub start_sub Opts gt ok pid error already started pidO error Reason Types e Opts opt e opt priority Prio Starts a supervisor for the SN MP agent system without a master agent The supervisor starts all involved SN MP processes but no agent processes Subagents should be started by calling start_subagent 3 Prio is an Erlang priority All SN MP processes use this priority D efault is the same as default in the Erlang runtime system start_master DbDir ConfDir start_master DbDir ConfDir Opts gt fok pid error already_started pid error Reason Types e DbDir string e ConfDir string e Opts opt e opt mibs Mibs net_if NetlfM odule priority Prio name Name e Mibs MibN ame e MibName strin
139. module which takes care of encryption and authentication that cannot be used with SN M Pv1 or SN MPv2c In this version of the agent toolkit all the standard M IBs for agent configuration are used This includes M IBs for definition of management targets for notifications These M Bs are used regardless of which SN MP version the agent is configured to use The extensible agent in this toolkit understands the SN M Pv1 SN MPv2c and SNM Pv3 Recall that SN MP consists of two separate parts the MIB definition language SM 1 and the protocol On the protocol level the agent can be configured to speak v1 v2c v3 or any combination of them at the same time i e a v1 request gets an v1 reply a v2c request gets a v2c reply and a v3 request gets a v3 reply On the MIB level the MIB compiler can compile both SM Iv1 and SM Iv2 MIBs Once compiled any of the formats can be loaded into the agent regardless of which protocol version the agent is configured to use This means that the agent translates from v2 notifications to v1 traps and vice versa For example v2 M IBs can be loaded into an agent that speaks v1 only The procedures for the translation between the two protocols are described in RFC 1908 and RFC 2089 In order for an implementation to make full use of the enhanced SN M Pv2 error codes it is essential that the instrumentation functions always return SN M Pv2 error codes in case of error These are translated into the corresponding SN
140. mp module snmp_mpd for more details There are also some useful functions for encoding and decoding of SNMP messages in the module snmp _pdus 1 11 SNMP Appendix A 1 11 1 Appendix A This appendix describes the conversion of SN M Pv2 to SNM Pv1 error messages The instrumentation functions should return v2 error messages M apping of SN MPv2 error message to SN M Pv1 noC reation noSuchN ame continued 58 Simple N etwork M anagement Protocol SN M P continued inconsistentV alue badV alue resourceU navailable undoFailed notW table inconsistentN ame Table 1 1 Error M essages 1 12 SNMP Appendix B 1 12 1 Appendix B RowStatus from RFC1903 RowStatus TEXTUAL CONVENTION STATUS current DESCRIPTION 1 12 SNMP Appendix B The RowStatus textual convention is used to manage the creation and deletion of conceptual rows and is used as the value of the SYNTAX clause for the status column of a conceptual row as described in Section 7 7 1 in RFC1902 The status column has six defined values active which indicates that the conceptual row is available for use by the managed device notInService which indicates that the conceptual row exists in the agent but is unavailable for use by the managed device see NOTE below notReady which indicates that the conceptual row exists in the agent but is missing information necessary in order to be available for use
141. mp manager app is now configurable recbuf integer see manager options page 132 N ote that the maximum size of outgoing incoming message should be set to a value less then or equal to the recbuf size See for example snmpEngineM axM essagesizein SNMP_FRAMEWORK_MIB N ote that this problem exists in R7 only Own Id OTP 3797 Aux Id seq5008 1 13 10 SNMP Development Toolkit v3 2 2 Version 3 2 2 supports code replacement in runtime from to version e OTP version R7 3 2 1 and 3 2 0 e OTP version R6 3 1 4 and 3 1 3 e OTP version R5 3 0 9 4 3 0 9 3 and 3 0 9 2 72 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Improvements and new features e It isnow possible to register unregister for notification of changes stored permanetly i e on disk in snmp_local_db Own Id OTP 3704 e Added direct access read functions to the symbolic store for faster access accessible throw the snmp page 101 module Own Id OTP 3725 1 13 11 SNMP Development Toolkit v3 2 1 Version 3 2 1 supports code replacement in runtime from to version 3 2 0 3 1 4 3 1 3 3 0 9 4 3 0 9 3 and 3 0 9 2 Reported Fixed Bugs and Malfunctions e Bad arith in snmp_pdus error case not handled Erronous user provided messages that could not be encoded caused the application to crash Own Id OTP 3688 Aux Id seq4874 1 13 12 SNMP Development Toolkit v3 2 0 Version 3 2 0 supports code replacement in runtime from to v
142. mpty string e CommunityName is a string e SecurityName isa string e ContextName isa string e TransportTag isa string Simple N etwork M anagement Protocol SN M P 47 Chapter 1 SNMP User s Guide 1 8 5 MIB Views for VACM The information about MIB Views for VACM should be stored in a file called vacm conf The corresponding tables are vacmSecurityToGroupTable vacmAccessTable and vacmViewTreeFamilyTable in the SN MP VIEW BASED ACM MIB Each entry is one of the terms one entry corresponds to one row in one of the tables vacmSecurityToGroup SecModel SecName GroupName vacmAccess GroupName Prefix SecModel SecLevel Match ReadView WriteView NotifyView vacmViewTreeFamily ViewIndex ViewSubtree ViewStatus ViewMask e SecModel is any vi v2c Or usm e SecName is a string e GroupName is a string e Prefix isa string e SecLevel iS noAuthNoPriv authNoPriv Or authPriv e Match is prefix Or exact e ReadView is a string e WriteView isa string e NotifyView is a string e ViewIndex is an integer e ViewSubtree is a list of integer e ViewStatus is either included or excluded e ViewMask is either null or a list of ones and zeros Ones nominate that an exact match is used for this sub identifier Zeros are wildcards which match any sub identifier If the mask is shorter than the subtree the tail is regarded as all ones nu11 is shorthand for a mask with all ones 1 8 6 Security data for USM
143. must be provided This parameter is used as an index in the snmpNotifyTable and the management targets defined by that single entry is used The send_notification 6 function is the most general version of the function A ContextName must be specified from which the notification will be sent If this parameter is not specified the default context is used The function send_trap is kept for backwards compatibility and should not be used in new code Applications that use this function will continue to work The snmpNotifyName is used as the community string by the agent when a notification is sent Notification Sending The simplest way to send a notification is to call the function snmp send_ notification Agent Notification no_receiver In this case the agent performs a get operation to retrieve the object values that are defined in the notification specification with the TRAP TY PE or NOTIFICATION TY PE macros The notification is sent to all managers defined in the target and notify tables either unacknowledged as traps or acknowledged as inform requests If the caller of the function wants to know whether or not acknowledgements are received for a certain notification provided it is sent as an inform the Receiver parameter can be specified as Tag ProcessName refer to the Reference M anual section snmp module snmp for more details In this case the agent send a message snmp_notification Tag got_response ManagerAddr
144. n is optional The return value is discarded f get ExtraArgs ThE function f get ExtraArgs is called when a get request or a get next request refers to the variable This function is mandatory 50 Simple N etwork M anagement Protocol SN M P 1 9 Definition of Instrumentation Functions Valid Return Values e value Value The Value must be of correct type length and within ranges otherwise genErr is returned in the response PDU If the object is an enumerated integer the symbolic enum value may be used as an atom If the object is of type BITS the return value shall be an integer or a list of bits that are set e noValue noSuchName SN M Pv1 e noValue noSuchObject noSuchInstance SNM Pv2 e genErr Used if an error occured Note this should be an internal processing error e g a caused by a programing fault somewhere If the variable does not exist use noValue noSuchName or noValue noSuchInstance f is_setok NewValue ExtraArgs ThE function f is_set_ok NewValue ExtraArgs is called in phase one of the set request processing so that the new value can be checked for inconsistencies NewValue is guaranteed to be of the correct type length and within ranges as specified in the M IB If the object is an enumerated integer or of type BITS the integer value is used This function is optional If this function is called it will be called again either with undo or with set as first argument
145. nctions for the SN MP VIEW BASED ACM MIB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is vacm conf reconfigure ConfDir gt void Types e ConfDir string Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configuration file will have StorageType nonVolatile Thus the data in the SN MP VIEW BASED ACM MIB after this function has been called isthe data from the configuration files All snmp counters are set to zero If an error isfound in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration_
146. nmp_mgr 130 generate_msg 4 snmp_mpd 135 generate_response_msg 4 snmp_mpd 134 get 2 snmp 105 snmp _index 124 get_agent_caps 0 snmp 105 get_index_types 1 snmp generic 119 get_last 1 snmp _index 124 get_next 2 snmp _index 124 get_status_col 2 snmp generic 119 get_symbolic_store_db 0 snmp 105 gn 0 snmp_mgr 131 gn 1 snmp_mgr 131 inc 1 snmp _standard_mib 140 inc 2 snmp _standard_mib 140 info 1 snmp 106 init 0 snmp _framework_mib 117 init_mpd 1 snmp_mpd 134 insert 3 snmp _index 124 int_to_enum 2 snmp 106 int_to_enum 3 snmp 106 is_consistent 1 snmp 106 key_to_oid 2 snmp _index 124 load_mibs 2 snmp 106 local_time_to_date_and_time 1 snmp 107 log_to_txt 2 snmp 107 log_to_txt 3 snmp 107 log_to_txt 4 snmp 107 log_to_txt 5 snmp 107 log_to_txt 6 snmp 107 log_to_txt 7 snmp 107 match 2 154 Simple N etwork M anagement Protocol SN M P snmp_local_db 127 mib_to_hrl1 1 snmp 108 name_to_oid 1 snmp 108 snmp_mgr 131 name_to_oid 2 snmp 108 new 1 snmp_index 125 oid_to_name 1 snmp 108 snmp_mgr 131 oid_to_name 2 snmp 108 print 0 snmp_local_db 127 print 1 snmp_local_db 127 print 2 snmp_local_db 127 process_packet 4 snmp_mpd 134 r o snmp_mgr 131 reconfigure 1 snmp_community_mib 113 snmp_notification_mib 136 snmp_standard
147. ns 1 3 1 Instrumentation Functions The following sections describe how the instrumentation functions should be defined in Erlang for the different operations In the following RowIndex is a list of key values for the table and Column is a column number These functions are described in detail in Definition of Instrumentation Functions page 50 New Delete Operations For scalar variables variable_access new ExtraArgl1 variable_access delete ExtraArgl1 For tables table_access new ExtraArgl table_access delete ExtraArgi These functions are called for each object in an MIB when the MIB is unloaded or loaded respectively Get Operation For scalar variables variable_access get ExtraArgl1 For tables table_access get RowIndex Cols ExtraArg1 Cols is alist of Column The agent will sort incoming variables so that all operations on one row same index will be supplied at the same time The reason for this is that a database normally retrieves information row by row These functions must return the current values of the associated variables Set Operation For scalar variables variable_access set NewValue ExtraArgi For tables table_access set RowIndex Cols ExtraArg1 Cols is alist of tuples Column NewValue These functions returns noError if the assignment was successful otherwise an error code Simple N etwork M anagement Protocol S
148. ns a correct DateAndTime structure Previously the sign in position 9 was wrong Own Id OTP 1838 Traps larger than the maximum packet size are now handled Own Id OTP 1850 Aux Id seq416 The snmp_note_store server never invoked its gc which meant that its intenal data structure could grow very large Own Id OTP 1946 Aux Id seq451 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Some objects in traps in SNMP v1 MIBs did not get the correct type in the compiled mib This could lead to that the trap could not be sent Own Id OT P 2063 1 13 29 SNMP Development Toolkit v2 0 Improvements and new features The agent is bilingual and understands SN M Pv1 and SN M Pv2c The agent is made multi threaded configurable option The agent can be configured to log requests to an Audit Trail Log The application is restructured to be able to restart large parts of the agent in case of an error The Netlf process API is simpler than in previous versions New functions for handling AGEN T CAPABILITES statements in the module snmp A few new M IBs are added to the distribution These are SN M Pv2 M IB and SNM Pv2 TC The INTERNAL MIB has changed its name to OTP SN M PEA M IB Added the coldStart and warmStart traps to the STA N DARD M IB None of them are sent by default though The STANDARD MIB and SNM Pv2 M IB defines the same objects and notifications except for the object specifc to v1 and v2 respectively
149. oduces more or less the same output i e the debug flag can be turned on to verify that the configuration is correct and that the instrumentation functions behave as expected The agent then shows all network communication incoming outgoing traffic and calls to the instrumentation functions 3 gt snmp debug snmp_master_agent true ok 4 gt h Example of output from the agent when a get next request arrives SNMP NET 1F LOG got paket from 147 12 12 12 5000 SNMP NET IF MPD LOG vi community all rights SNMP NET IF LOG got pdu from 147 12 12 12 5000 pdu get next request 62612569 noError 0O 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 gt OCTET STRING Erlang SNMP agent 1 SNMP NET 1F INFO time in agent 19711 mysec Another useful function for debugging is snmp_local_db print 0 1 2 For example this function can show the counters snmpInPkts and snmpOutPkts Enter the following command 4 gt snmp_local_db print Ah A lot of information 30 Simple N etwork M anagement Protocol SN M P 1 6 Implementation Example 1 6 Implementation Example The section Implementation Example describes how an MIB can
150. ok pidQ error already_started pid ferror Reason page 142 Start the SNMP supervisor for all agents e start_subagent ParentAgent Subtree Mibs gt ok pidQ error Reason page 143 Start a subagent e stop_subagent SubAgent gt ok no_such_child page 143 Stop a subagent Simple N etwork M anagement Protocol SN M P 97 98 SNMP Reference Manual snmp_target_mib The following functions are exported e configure ConfDir gt void page 144 Configure the SN MP TARGET MIB e reconfigure ConfDir gt void page 144 Configure the SN MP TARGET MIB e set_target_engine_id TargetAddrName Engineld gt boolean page 145 Set the engine id for a targetA ddr row snmp_user_based_sm_mib The following functions are exported e configure ConfDir gt void page 146 Configure the SN MP USER BA SED SM MIB e reconfigure ConfDir gt void page 146 Configure the SN MP USER BA SED SM MIB snmp_view_based_acm_mib The following functions are exported e configure ConfDir gt void page 147 Configure the SN M P V IEW BA SED ACM MIB e reconfigure ConfDir gt void page 147 Configure the SN M P V IEW BA SED AC M M IB Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp snmp Application This chapter describes the snmp application in OTP The SNMP application provides the following services e amultilingual extensible S
151. ol SN M P 19 Chapter 1 SNMP User s Guide Figure 1 6 GetN ext from 3 1 1 and 5 1 1 The manager now issues the following getNext request getNext myTable myTableEntry 3 2 1 myTable myTableEntry 5 2 1 This is transformed into one call to my_table my_table get_next 2 1 3 5 The function should now return X 4 1 1 b endOfTable Thisisillustrated in the following table a AA O endOf Table Figure 1 7 GetN ext from 3 2 1 and 5 2 1 The manager now issues the following getNext request 20 Simple N etwork M anagement Protocol SN M P 1 3 Instrumentation Functions getNext myTable myTableEntry 3 1 2 myTable myTableEntry 4 1 2 This will be transform into one call to my_table my_table get_next 1 2 3 4 The function should now return 3 2 1 gt f 5 1 1 ch This is illustrated in the following table Figure 1 8 GetN ext from 3 1 2 and 4 1 2 The manager now issues the following getNext request getNext myTable myTableEntry myTable myTableEntry 1 3 2 This will be transform into two calls to my_table my_table get_next 0 and my_table get_next 3 2 1 The function should now return X 3 1 1 a and X 3 1 11 a In both cases the first accessible element in the table should be returned As the key columns are not accessible this means that the third column is the first row N ote Normally the functions described
152. ommunity send_trap Agent Trap Community Varbinds gt void Types e Agent pid atom e Trap atom e Community string e Varbinds Varbind e Varbind Variable Value Column RowIndex Value OID Value e Variable atom 110 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp e Column atom e OID oid e Value term e Rowlndex int N ote This function is only kept for backwards compatibility reasons Use send_notification instead Sends the trap Trap to the managers defined for Community in the intTrapDestTable in OTP SNMPEA MIB The optional argument Varbinds defines values for the objects in the trap If no value is given for an object the Agent performs a get operation to retrieve the value Varbinds is alist of Varbind where each Varbind is one of e Variable Value where Variable is the symbolic name of a scalar variable referred to in the trap specification e Column RowIndex Value where Column is the symbolic name of a column variable RowIndex is a list of indices for the specified element If this is the case the OBJECT IDENTIFIER sent in the trap is the RowIndex appended to the OBJECT IDENTIFIER for the table column Thisisthe OBJECT IDENTIFIER which specifies the element e 0ID Value where OID isthe OBJECT IDENTIFIER for an instance of an object scalar variable or column variable For example to specify that sysLocation should have the
153. onfig_err 2 of the error report module and the function fails with reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is community conf reconfigure ConfDir gt void Types e ConfDir string Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configuration file will have StorageType nonVolatile Thus the data in the SNMP COMMUNITY MIB after this function has been called is from the configuration files All snmp counters are set to zero If an error isfound in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is community conf Simple N etwork M anagement Protocol SN M P 113 snmp_error SNMP Reference Manual SNM P_error Erlang Module The module snmp_error contains two callback functions which are called by snmp_error_report in order to report SNMP errors This module provides a simple mechanism for reporting SN MP errors Errors are sent to the error_logger after a size check M essages are truncated after 1024 chars It is provided as an example This module is the default error re
154. ow NewVal T merge_rows Row gt Row Association File The association file EX1 MIB funcs for the real implementation looks as follows myName ex1 my_name friendsTable fex1 friends_table Transcript To use the real implementation we must recompile the MIB and load it into the agent 1 gt application start snmp ok 2 gt snmp c EX1 MIB ok EX1 MIB bin 3 gt snmp loadmibs snmpmaster_agent EX1 MIB ok 4 gt exi startQ lt 0 115 0 gt Now all requests operates on this real implementation The output from the manager requests will look exactly the same as for the default implementation Trap Sending How to send atrap by sending the fTrap from the master agent is shown in this section The master agent has the MIB EX1 MIB loaded where the trap is defined This trap specifies that two variables should be sent along with the trap myName and fIndex fIndex is a table column so we must provide its value and the index for the row in the call to snmp send_trap 4 In the example below we assume that the row in question is indexed by 2 the row with fIndex 2 we use a simple Erlang SN MP manager which can receive traps 38 Simple N etwork M anagement Protocol SN M P 1 7 Advanced Topics MANAGER 1 gt snmpmgr start_link agent dront ericsson se community public 9 does not have write access 1 gt mibs EX1 MIB STANDARD MIB TO
155. owIndex Cols gt notify_internal_resources RowIndex Cols NewCols case is_row_created empTable Cols of true gt Cols 4 internal add internal column false gt Cols keep original cols end snmp_generic table_func set RowIndex NewCols fempTable mnesia emp_table Op RowIndex Cols gt snmp_generic table_func Op RowIndex Cols empTable mnesia is_row_created Name Cols gt case snmp_generic get_status_col Name Cols of lok createAndGo gt true lok createAndWait gt true _ gt false end If arow is created we always set the internal column to internal 1 7 7 Audit Trail Logging The agent can be configured to log incoming requests and outgoing responses and traps It uses the Erlang standard log mechanism disk_log for logging The size and location of the log files are configurable A wrap log is used which means that when the log has grown to a maximum size it starts from the beginning of the log overwriting existing log records The log can be either a write_log or aread_write_log In a write_log all set requests and their responses are stored No get requests or traps are stored in a write_log In aread_write_log all requests responses and traps are stored The log uses a raw data format basically the BER encoded message in order to minimize the C PU load needed for the log mechanism This means that the log is not human readable but needs to be formatted off line b
156. p c MY MIB il snmp priv mibs myapp priv mibs finds the lastest version of the snmp and myapp applications in the OTP system and uses the expanded paths as include paths Note that an SM Iv2 MIB can import an SMIv1 MIB and vice versa The following M IBs are built ins of the Erlang SN MP compiler SNM Pv2 SM 1 RFC 1215 RFC 1212 SNM Pv2 TC SNM Pv2 CONF and RFC1155 SM 1 They cannot therefore be compiled separately 1 43 MIB Consistency Checking When an MIB is compiled the compiler detects if several managed objects use the same OBJECT IDENTIFIER If that is the case it issues an error message H owever the compiler cannot detect O id conflicts between different MIBs These kinds of conflicts generate an error at load time To avoid this the following function can be used to do consistency checking between M IBs erl gt snmp is_consistent ListOfMibNames ListOfMibNames is a list of compiled MIBs for example RFC1213 MIB MY MIB The function also performs consistency checking of trap definitions 1 4 4 hrl File Generation It is possible to generate an hr1 file which contains definitions of Erlang constants from a compiled MIB file This file can then be included in Erlang source code The file will contain constants for e object Identifiers for tables table entries and variables e column numbers e enumerated values e default values for variables and table columns Use the following command to gene
157. p error_io 115 snmp_error_report 116 configure 1 snmp_community_mib 113 snmp_framework_mib 117 snmp_notification_mib 136 snmp_standard_mib 140 snmp_target_mib 144 snmp_user_based_sm_mib 146 snmp_view_based_acm_mib 147 current_address 0 snmp 103 current_community 0 snmp 103 current_context 0 snmp 103 current_net_if_data 0 snmp 103 current_request_id 0 snmp 103 date_and_time 0 snmp 104 date_and_time_to_string 1 snmp 104 date_and_time_to_universal_time 1 snmp 104 debug 2 snmp 104 dec_message 1 snmp _pdus 137 dec_message_only 1 snmp _pdus 137 dec_pdu 1 snmp pdus 137 dec_scoped_pdu 1 snmp pdus 138 dec_scoped_pdu_data 1 snmp pdus 138 dec_usm_security_parameters 1 snmp pdus 138 del_agent_caps 1 snmp 104 delete 1 snmp _index 123 delete 2 snmp _index 124 discarded_pdu 1 snmp_mpd 135 dump 0 snmp _local_db 127 enc_encrypted_scoped_pdu 1 snmp pdus 138 enc_message 1 snmp pdus 138 enc_message_only 1 Simple N etwork M anagement Protocol SN M P 153 Index of Modules and Functions snmp pdus 138 enc_pdu 1 snmp pdus 138 enc_scoped_pdu 1 snmp pdus 138 enc_usm_security_parameters 1 snmp pdus 139 enum_to_int 2 snmp 104 enum_to_int 3 snmp 105 expect 2 snmp_mgr 130 expect 3 snmp_mgr 130 expect 4 snmp_mgr 130 expect 6 snmp_mgr 130 g 1 snmp_mgr 130 gb 3 s
158. pes e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and destroys all old rows with StorageType volatile The rows created from the configuration file will have StorageType nonVolatile All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report module and the function fails with the reason configuration_error ConfDir is a string which points to the directory where the configuration files are found The configuration file read is standard conf inc Name gt void inc Name N gt void Types e Name atom e N integer Increments a variable in the MIB with N or one if N is not specified reconfigure ConfDir gt void Types e ConfDir string 140 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp standard_mib Inserts all data in the configuration files into the database and destroys all old data including the rows with StorageType nonVolatile The rows created from the configuration file will have StorageType nonVolatile Thus the data in the SN MP STANDARD MIB and SNM Pv2 M IB after this function has been called is from the configuration files All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the error report
159. port module but can be explicitly configured see snmp error_report page 116 and configuration parameters page 27 Exports config_err Format Args gt void Types e Format string e Args list The function is called if an error occurs during the configuration phase for example if a syntax error is found in a configuration file Format and Args are asin io format Format Args user_err Format Args gt void 114 Types e Format string e Args list The function is called if a user related error occurs at runtime for example if a user defined instrumentation function returns erroneous Format and Args are asin io format Format Args See Also error_logger 3 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp error_io snmp_error_io Erlang Module The module snmp_error_io contains two callback functions which are called by snmp_error_report in order to report SN MP errors This module provides a simple mechanism for reporting SN MP errors Errors are written to stdout using the io module It is provided as an simple example This module needs to be explicitly configured see snmp _error_report page 116 and configuration parameters page 27 Exports config_err Format Args gt void Types e Format string e Args list The function is called if an error occurs during the configuration phase for example if a syntax error is found in a conf
160. ppropriate configuration file Configuration Files page 27 1 2 7 Management of the Agent There is a set of standard M IBs which are used to control and configure an SN MP agent All of these MIBs with the exception of the optional SN M P PRO X Y M IB which is only used for proxy agents are implemented in this agent Further it is configurable which of these MIBs are actually loaded and thus made visible to SN MP managers For example in a non secure environment it might be a good idea to not make M IBs that define access control visible N ote the data the M IBs define is used internally in the agent even if the M IBs not are loaded This chapter describes these standard MIBs and some aspects of their implementation Any SNMP agent must implement the system group and the snmp group defined in MIB II The definitions of these groups have changed from SN M Pv1 to SNM Pv2 MIBs and implementations for both of these versions are Provided in the distribution The MIB file for SN M Pv1 is called Simple N etwork M anagement Protocol SN M P 9 Chapter 1 SNMP User s Guide STANDARD MIB and the corresponding for SN M Pv2 is called SN M Pv2 M IB If the agent is configured for SN M Pv1 only the STANDARD MIB is loaded by default otherwise the SN M Pv2 M IB is loaded by default It is possible to override this default behavior by explicitly loading another version of this MIB for example you could choose to implement the union of all ob
161. process_packet Packet TDomain TAddress State gt ok Vsn Pdu PduMS ACMData discarded Reason page 134 Process a packet received from the network e generate_response_msg Vsn RePdu Type ACMData gt ok Packet discarded Reason page 134 Generate a response packet to be sent to the network e generate msg Vsn Pdu MsgData To gt ok PacketsAndAddresses discarded Reason page 135 Generate a request message to be sent to the network discarded_pdu Variable gt void page 135 Increment the variable associated with a discarded pdu snmp_notification_mib The following functions are exported e configure ConfDir gt void page 136 Configure the SNM P NOTIFICATION MIB e reconfigure ConfDir gt void page 136 Configure the SN MP NOTIFICATION MIB snmp_pdus The following functions are exported e dec_message byte gt Message page 137 Decode an SN MP Message e dec_message_only byte gt Message page 137 Decode an SNMP M essage but not the data part e dec_pdu byte gt Pdu page 137 Decode an SN MP Pdu e dec_scoped_pdu byte gt ScopedPdu page 138 Decode an SN MP ScopedPdu e dec_scoped_pdu_data byte gt ScopedPduData page 138 Decode an SN MP ScopedPduD ata e dec_usm_security_parameters byte gt UsmSecParams page 138 Decode SN MP UsmSecurityParameters e enc_encrypted_scoped_pdu EncryptedScopedPdu gt byte page 13
162. pter 1 SNMP User s Guide 1 13 9 SNMP Development Toolkit v3 3 0 Version 3 3 0 supports code replacement in runtime from to version 3 2 2 N ote You cannot downgrade if you are using dets or mnesia for mib data storage since previous versions only supported ets Improvements and new features e The agent can now load mibs compiled with a pre 3 2 0 mib compiler Own Id OTP 3833 e Added anew interface function to retrieve the index types of the table info This was previously internal info only See the generic functions page 118 Own Id OTP 3816 Aux Id seq5053 e Itis now possible to store mib data in ets dets and mnesia Default is ets See configuration parameters page 27 on how to configure this Own Id OTP 3740 Aux Id seq4947 Reported Fixed Bugs and Malfunctions e The EVA application called undefined SN MP log conversion function Own Id OTP 3733 Snmp manager get bulk request failure This is actually aUDP problem OTP 3807 In R7 the default receive buffer recbuf size of a UDP socket has incorrectly been changed to 1024 bytes The problem is that when a message bigger then the recbuf size is received it is cut and sizeof recbuf bytes is delivered this is not the correct behaviour The simple snmp manager app included in this application did not explicitly set the size of recbuf So in R7 a get bulk request could easily exceed 1024 bytes resulting in an erroneous message The size of recbuf for the sn
163. r 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 M anual for a description of how to change the log size The change is permanent as long as the log is not deleted That means the log size is remebered across reboots config gt ok ferror Reason 102 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp A simple interactive SN MP agent configuration tool Simple configuration files can be generated but more complex configurations still have to be edited manually The tool is a textual based tool that asks some questions and generates sys config and conf files current_address gt value IP UDP false Types e IP int int int int e UDP int Retrieves the IP address of the management station sending the request It must be called from the same process that is handling the request normally an instrumentation function Returns false if no request is currently handled current_community gt value Community false Types e Community string Retrieves the community referred to in the current request It must be called from the same process that is handling the request normally an instrumentation function Returns false if no request is currently handled NOTE This function should only be used if the agent speaks SN M Pv1 or SNM Pv2c
164. r extra variables that should be sent in the notification but were not defined in the notification specification The notification is sent to all management targets found in the tables However make sure that each manager has access to the variables in the notification If a variable is outside a manager s M IB view this manager will not receive the notification Note By definition it is not possible to send objects with ACCESS not accessible in notifications However historically this is often done and for this reason we allow it in notification sending If a variable has AC CESS not accessible the user must provide a value for the variable in the Varbinds list It is not possible for the agent to perform a get operation to retrieve this value Subagent Path If avalue for an object is not given to the send_notification function the subagent will perform a get operation to retrieve it If the object is not implemented in this subagent its parent agent tries to perform a get operation to retrieve it If the object is not implemented in this agent either it forwards the object to its parent and so on Eventually the M aster Agent is reached and at this point all unknown object values must be resolved If some object is unknown even to the Master Agent this is regarded as an error and is reported with a call to user_err 2 of the error report module No notifications are sent in this case For a given notification the variables which are
165. r must be defined bind_to_ip_address bool lt optional gt If true the agent binds to the agent IP adress If false the agent listens on any IP address on the host where it is running Default is false force_config_load bool lt optional gt If true the configuration files are re read during startup and the contents of the configuration database ignored Thus if true changes to the configuration database are lost upon reboot of the agent D efault is false no_reuse_address bool lt optional gt If true the agent does not specify that the IP and port address should be reusable If false the agent the address is set to reusable Default is false snmp_agent_type master sub lt optional gt If master one master agent is started O therwise no agents are started Default ismaster snmp_config dir string lt mandatory gt Defines where the SNMP configuration files and the compiled master agent M IB files are stored snmp_db_dir string lt mandatory gt Defines where the SNMP internal db files are stored snmp_master_agentmibs string lt optional gt Specifies a list of MIB names and defines which M IBs are initially loaded into the SNMP master agent These M IBs are loaded from snmp_config_dir Simple N etwork M anagement Protocol SN M P 27 Chapter 1 SNMP User s Guide snmpmulti_threaded bool lt optional gt If true the agent is multi threaded with one thread for each get request D efault is fals
166. r rows in atable shall be visible SNMP COMMUNITY MIB The SNMP COMMUNITY MIB defines managed objects that is used for coexistence between SNM Pv1 and SN MPv2c with SNM Pv3 Specifically it contains objects for mapping between community strings and version independent SN M P message parameters In addition this MIB provides a mechanism for performing source address validation on incoming requests and for selecting community strings based on target addresses for outgoing notifications All tables in this MIB have acolumn of type StorageType The value of this column specifies how each row is stored and what happens in case of a restart of the agent The implementation supports the values volatile and nonVolatile When the tables are initially filled with data from the configuration files these rows will automatically have storage type nonVolatile Should the agent restart all nonVolatile rows survive the restart while the volatile rows are lost The configuration files are not read at restart by default This MIB is not loaded by default SNMP USER BASED SM MIB The SN MP USER BA SED SM MIB defines managed objects that is used for the User Based Security M odel All tables in this MIB have acolumn of type StorageType The value of the column specifies how each row is stored and what happens in case of a restart of the agent The implementation supports the values volatile and nonVolatile When the tables are initially filled with data
167. rate a hrl file from an MIB erl gt snmp mib_to_hrl MibName 1 4 5 Emacs Integration With the Emacs editor the next error C X function can be used indicate where a compilation error occurred provided the error message is described by a line number Use M x compile to compile an M IB from inside Emacs and enter erl s snmp c lt MibName gt noshell An example of lt MibName gt iS RFC1213 MIB Simple N etwork M anagement Protocol SN M P 25 Chapter 1 SNMP User s Guide 1 4 6 Compiling from a Shell or a Makefile The erlc commands can be used to compile SN MP MIBs Example erlc MY MIB mib All the standard erlc flags are supported e g erlc I mymibs o mymibs W MY MIB mib The flags specific to the MIB compiler can be specified by using the syntax erlc group_check false MY MIB mib 1 4 7 Deviations from the Standard In some aspects the Erlang MIB compiler does not follow or implement the SMI fully Here are the differences 26 Tables must be written in the following order tableObject entry0bject columni columnN in order Integer values for example in the SIZE expression must be entered in decimal syntax not in hex or bit syntax Symbolic names must be unique within a MIB and within a system Hyphens are allowed in SM Iv2 a pragmatic approach The reason for this is that according to SM lv2 hyphens are allowed for objects converted from SM Iv1 but not for others Th
168. re pending e ErrorStatus is an atom which describes an error message See documentation for the SN MP agent e Varbinds isa list of Oid Value Oid any If a response other than the expected one is received an error message is displayed and and error Id Reason is returned A call to expect is normally directly preceeded by sending a message The reply to a received Inform request can be controlled If InformReply iS true a noError reply is sent If it is false no reply is sent If itis error ErrorStatus ErrorIndex a reply indicating the error is sent g Oids gt void Types e Oids oid Sends a get request gb NonRepeaters MaxRepetitions Oids gt void 130 Types e NonRepeaters integer e MaxRepetitions integer e Oids oid Sends a get bulk request See RFC 1905 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_mgr gn Oids gt void Types e Oids oid Sends a get next request gn gt voidO Sends yet another get next request constructed from the previous response Thisisa nice feature for manually traversing a M IB gn N gt void Types e N integer Sends N get next request requests The last response is used as the start value Works somewhat like a get bulk request see SNM Pv2 r gt void Resend the last request oid_to_name 0id gt ok Name error Reason Types e Oid oid e Name atom Transform
169. res To implement an agent the programmer writes instrumentation functions for the variables and the tables in the MIBs that the agent is going to support A running prototype which handles set get and get next Can be created without any programming The toolkit provides the following e multi lingual multi threaded extensible SN MP agent e easy writing of instrumentation functions with a high level programming language basic fault handling such as automatic type checking access control authentication privacy through encryption loading and unloading of MIBsin runtime the ability to change instrumentation functions without recompiling the MIB rapid prototyping environment where the MIB compiler can use generic instrumentation functions which later can be refined by the programmer asimple and extensible model for transaction handling and consistency checking of set requests support of the subagent concept via distributed Erlang e amechanism for sending notifications traps and informs support for implementing SN MP tables in the M nesia DBMS 1 2 3 SNMPv1 SNMPv2 and SNMPv3 The SNMP development toolkit works with all three versions of Standard Internet M anagement Framework SN M Pv1 SNM Pv2 and SNM Pv3 They all share the same basic structure and components And they follow the same architecture The versions are defined in following RFCs e SNMPv1 RFC 1555 1157 1212 1213 and 1215 e SNMPv2 RFC 1902 1907 e SNMPv3 RFC 2
170. returns the tuple Next0id NextValue or endOfTable Next0id should be the lexicographically next accessible instance of a managed object in the table It should be a list of integers where the first integer is the column and the rest of the list is the indices for the next row If endOfTable is returned the agent continues to search for the next instance among the other variables and tables RowIndex may be an empty list an incompletely specified row index or the index for an unspecified row This operation is best described with an example 18 Simple N etwork M anagement Protocol SN M P 1 3 Instrumentation Functions GetNext Example A table called myTable has five columns The first two are keys not accessible and the table has three rows The instrumentation function for this table is called my_table Figure 1 5 Contents of my_table N ote N A means not accessible The manager issues the following getNext request getNext myTable myTableEntry 3 1 1 myTable myTableEntry 5 1 1 Since both operations involve the 1 1 index this is transformed into one call to my_table my_table get_next 1 1 3 5 In this call 1 1 isthe RowIndex where key 1 has value 1 and key 2 has value 1 and 3 5 isthe list of requested columns The function should now return the lexicographically next elements X 3 1 2 da 5 1 2 f This is illustrated in the following table Simple N etwork M anagement Protoc
171. rformed This phase calls the user defined set function for all variables If an error occurs either in the is_set_ok phase or in the set phase all functions which were called with is_set_ok but not set are called with undo There are limitations with this transaction mechanism If complex dependencies exist between variables for example between month and day another mechanism is needed Setting the date to Feb 31 can be avoided by a somewhat more generic transaction mechanism You can continue and find more and more complex situations and construct an N phase set mechanism This toolkit only contains atrivial mechanism The most common application of transaction mechanisms is to keep row operations together Since our agent sorts row operations the mechanism implemented in combination with the RowStatus particularly createA ndW ait value solve most problems elegantly Simple N etwork M anagement Protocol SN M P 23 Chapter 1 SNMP User s Guide 1 4 The MIB Compiler The chapter The MIB C ompiler describes the MIB compiler and contains the following topics e Operation e Import e Consistency checking between MIBs e hrl file generation e Emacs integration e Deviations from the standard Note W hen importing MIBs ensure that the imported M IBs as well as the importing MIB are compiled using the same version of the SN M P compiler 1 4 1 Operation The MIB must be written as a text file in SM Iv1 or SM Iv2 u
172. rforms a get operation to retrieve the value Varbinds is alist of Varbind where each Varbind is one of e Variable Value where Variable is the symbolic name of a scalar variable referred to in the notification specification e Column RowIndex Value where Column is the symbolic name of a column variable RowIndex is a list of indices for the specified element If this is the case the OBJECT IDENTIFIER sent in the notification is the RowIndex appended to the OBJECT IDENTIFIER for the table column This is the OBJECT IDENTIFIER which specifies the element e OID Value where OID isthe OBJECT IDENTIFIER for an instance of an object scalar variable or column variable For example to specify that sysLocation should have the value upstairs in the notification we could use one of e sysLocation upstairs or e 1 3 6 1 2 1 1 6 0 upstairs or e sysLocation_instance upstairs provided that the generated hr1 file is included If a variable in the notification is a table element the RowIndex for the element must be given in the Varbinds list In this case the OBJECT IDENTIFIER sent in the notification isthe OBJECT IDENTIFIER that identifies this element This OBJECT IDENTIFIER could be used in a get operation later This function is asynchronous and does not return any information If an error occurs user_err 2 of the error report module is called and the notification is discarded send_trap Agent Trap C
173. ription of a collection of managed objects SMI The MIB is specified in an adapted subset of the Abstract Syntax N otation O ne ASN 1 language This adapted subset is called the Structure of Management Information SM1 ASN 1 ASN 1 isused in two different ways in SNMP The SMI is based on ASN 1 and the messages in the protocol are defined by using ASN 1 Managed object A resource to be managed is represented by a managed object which resides in the MIB In an SNMP MIB the managed objects are either scalar variables which have only one instance per context They have single values not multiple values like vectors or structures tables which can grow dynamically e atable element which is a special type of scalar variable O perations SN MP relies on the three basic operations get object set object value and get next object Instrumentation function An instrumentation function is associated with each managed object This is the function which actually implements the operations and will be called by the agent when it receives a request from the management station Manager A manager generates commands and receives notifications from agents There usually are only a few managers in a system Agent An agent respondsto commands from the manager and sends notification to the manager There are potentially many agents in a systrem Simple N etwork M anagement Protocol SN M P 3 Chapter 1 SNMP User s Guide 1 2 2 Featu
174. ror is the same as set for variables and Column denotes the faulty column Column must be one of the columns in the Cols list 1 10 Definition of Net if Bytes Erlang Terms Master AS A Agent Proxy agent specific representation Proxy Agent Subsystem Figure 1 9 The Purpose of N et if The Network Interface N et if process delivers SN M P PD Usto a master agent and receives SN M P PDUsfrom the master agent The most common behaviour of a Net if process is that is receives bytes from a network decodes them into an SN MP PDU which it sends to a master agent W hen the master agent has processed the PD U it sends a response PDU to the N et if process which encodes the PD U into bytes and transmits the bytes onto the network H owever that simple behaviour can be modified in numerous ways For example the N et if process can apply some kind of encrypting decrypting scheme on the bytes or act as a proxy filter which sends some packets to a proxy agent and some packets to the master agent It is also possible to write your own N et if process The default N et if process is implemented in the module snmp_net_if and it uses U DP as the transport protocol This section describes how to write a N et if process Simple N etwork M anagement Protocol SN M P 55 Chapter 1 SNMP User s Guide 1 10 1 Mandatory Functions A Net if process must be implemented in a module that exports the Module start_link 2 function which starts
175. rts export start 0 my_name 1 my_name 2 friends_table 3 Internal exports export init 0 define status_col 4 define active 1 define notInService 2 define notReady 3 define createAndGo 4 Action written not read define createAndWait 5 Action written not read define destroy 6 Action written not read start gt spawn ex1 init MINT ZII O O a Instrumentation function for variable myName Returns get value Name hh set noError my_name get gt exi_server self get_my_name Name wait_answer value Name my_name set NewName gt exi_server self set_my_name NewName noError friends_table get RowIndex Cols gt case get_row RowIndex of lok Row gt get_cols Cols Row gt noValue noSuchInstance end friends_table get_next RowIndex Cols gt 34 Simple N etwork M anagement Protocol SN M P 1 6 Implementation Example case get_next_row RowIndex of fok Row gt get_next_cols Cols Row gt case get_next_row of lok Row gt Get next cols from first row NewCols add_one_to_cols Cols get_next_cols NewCols Row gt end_of_table Cols end UN gt If RowStatus is set then hh If set to destroy check that row does exist Ah If set to createAndGo check that row does not exist AND hh that all columns are given values VA Otherwise error for simplicity
176. s NameDb The funcs file would look like myTable myModule myTabletfunc myTable mnesia Simple N etwork M anagement Protocol SN M P 121 snmp index 122 SNMP Reference Manual snmp_index Erlang M odule The module snmp_index implements an A bstract Data Type ADT for an SNMP index structure for SN MP tables It is implemented as an ets table of the ordered_set data type which means that all operations are O log n In the table the key is an ASN 1 OBJECT IDENTIFIER This index is used to separate the implementation of the SN MP ordering from the actual implementation of the table The SN MP ordering that is implementation of GET NEXT isimplemented in this module For example suppose there is an SNMP table which is best implemented in Erlang as one process per SN MP table row Suppose further that the INDEX in the SNMP table isan OCTET STRING The index structure would be created as follows snmp_index new string For each new process we create we insert an item in an snmp_index structure new_process Name SnmpIndex gt Pid start_process NewSnmpIndex snmp_index insert SnmpIndex Name Pid a With this structure we can now map an OBJECT IDENTIFIER ineg aGET NEXT request to the correct process get_next_pid 0id SnmpIndex gt fok _ Pid snmp_index get_next SnmpIndex Did Pid Common data types The following data types are used in the functions below e index e
177. s textual convention may be used for a MIB table irrespective of whether the values of that table s conceptual rows are able to be modified while it is active or whether its conceptual rows must be taken out of service in order to be modified That is it is the responsibility of the DESCRIPTION clause of the status column to specify whether the status column must not be active in order for the value of some other column of the same conceptual row to be modified If such a specification is made affected columns may be changed by an SNMP set PDU if the RowStatus would not be equal to active either immediately before or after processing the PDU In other words if the PDU also contained a varbind that would change the RowStatus value the column in question may be changed if the RowStatus was not equal to active as the PDU was received or if the varbind sets the status to a value other than active Also note that whenever any elements of a row exist the RowStatus column must also exist To summarize the effect of having a conceptual row with a status column having a SYNTAX clause value of RowStatus consider the following state diagram STATE A B C D status col status column status column is is status column 60 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B ACTION does not exist notReady notInService is
178. s to the SNMP toolkit Erlang M odule snmp_community_mib page 113 Instrumentation Functions for SNMP COMMUNITY MIB Erlang M odule snmp error page 114 Functions for Reporting SN MP Errors through the error_logger Erlang M odule snmp error_io page 115 Functions for Reporting SN MP Errors on stdio Erlang M odule snmp error_report page 116 Functions for Reporting SN MP Errors Erlang M odule snmp_framework_mib page 117 Instrumentation Functions for SNM P FRAMEWORK MIB Erlang M odule snmp generic page 118 Generic Functions for Implementing SNMP Objects in a Database Erlang M odule snmp_index page 122 Abstract Data Type for SN MP Indexing Erlang M odule snmp_local_db page 126 The SN MP built in database Erlang M odule snmp_mgr page 129 SN MP M anager Erlang M odule snmp_mpd page 134 M essage Processing and Dispatch module for SNMP Erlang M odule snmp_notification_mib page 136 Instrumentation Functions for SNMP NOTIFICATION MIB Erlang M odule snmp_pdus page 137 Encode and D ecode Functions for SN MP PDUs Erlang M odule snmp_standard_mib page 140 Instrumentation Functions for STANDARD MIB and SNM Pv2 M IB Erlang M odule snmp _supervisor page 142 A supervisor for the SN MP Processes Erlang M odule snmp _target_mib page 144 Instrumentation Functions for SN M P TARGET MIB Erlang M odule snmp_user_based_sm_mib page 146 Instrumentation Functions for SN MP USER BASED SM M
179. sName MPModel SecurityModel SecurityName SecurityLevel e ParamsName iS a unique non empty string e MPModel is v1 v2c or v3 e SecurityModel isv1 v2c Or usm e SecurityName is a string e SecurityLevel iSnoAuthNoPriv authNoPriv Or authPriv 1 9 Definition of Instrumentation Functions The section Definition of Instrumentation Functions describes the user defined functions which the agent calls at different times 1 9 1 Variable Instrumentation For scalar variables a function f Operation must be defined The Operation can be new delete get is_set_ok set Or undo In case of an error all instrumentation functions may return either an SN M Pv1 or an SNM Pv2 error code If it returns an SN M Pv2 code it is converted into an SN M Pv1 code before it is sent to a SN M Pv1 manager It is recommended to use the SN M Pv2 error codes for all instrumentation functions as these provide more details See Appendix A page 58 for a description of error code conversions f new ExtraArgs The function f new ExtraArgs is called for each variable in the MIB when the MIB is loaded into the agent This makes it possible to perform necessary initialization This function is optional The return value is discarded f delete ExtraArgs THE function f delete ExtraArgs is called for each object in an MIB when the MIB is unloaded from the agent This makes it possible to perform necessary clean up This functio
180. set In case of an error all instrumentation functions may return either an SN M Pv1 or an SNM Pv2 error code If it returns an SN M Pv2 code it is converted into an SN M Pv1 code before it is sent to a SN M Pv1 manager It is recommended to use the SN M Pv2 error codes for all instrumentation functions as these provide more details See Appendix A page 58 for a description of error code conversions f new ExtraArgs The function f new ExtraArgs is called for each object in an MIB when the MIB is loaded into the agent This makes it possible to perform the necessary initialization This function is optional The return value is discarded f delete ExtraArgs The function f delete ExtraArgs is called for each object in an MIB when the MIB is unloaded from the agent This makes it possible to perform any necessary clean up This function is optional The return value is discarded f get RowIndex Cols ExtraArgs The function f get RowIndex Cols ExtraArgs is called when a get request refers to a table This function is mandatory Arguments e RowIndex isa list of integers which define the key values for the row The RowIndex is the list representation list of integers which follow the Cols integer in the OBJECT IDENTIFIER e Cols isa list of integers which represent the column numbers The Cols are sorted by increasing value and are guaranteed to be valid column numbers 52 Simple N etwork M ana
181. sing an ASN 1 notation before it will be compiled This text file must have the same name as the M IB but with the suffix mib This is necessary for handling the IMPORT statement The association file which contains the names of instrumentation functions for the MIB should have the suffix funcs If the compiler does not find the association file it gives a warning message and uses default instrumentation functions See Default Instrumentation page 22 for more details The MIB compiler is started with a call to snmp c lt mibname gt For example snmp c RFC1213 MIB The output is a new file which is called lt mibname gt bin The MIB compiler understands both SM Iv1 and SM Iv2 MIBs It usesthe MODULE IDENTITY statement to determinate if the M IB is written in SM I version 1 or 2 1 4 2 Importing MIBs The compiler handles the IMPORT statement It is important to import the compiled file and not the ASN 1 file A MIB must be recompiled to make changes visible to other MIBs importing it The compiled files of the imported M IBs must be present in the current directory or a directory in the current path The path is supplied with the i Path option for example snmp c MY MIB fi friend_mibs standard_mibs It is also possible to import MIBs from OTP applications in an include_1ib like fashion with the 11 option Example 24 Simple N etwork M anagement Protocol SN M P 1 4 The MIB Compiler snm
182. snmp_mpd generate_message 4 In SNM Pv1 and SNM Pv2c this message data is the community string In SN M Pv3 it is the context information To isalist of the destination addresses and their corresponding security parameters This value is normally sent to snmp_mpd generate message 4 e send _pdu_req Vsn Pdu MsgData To Pid This message is sent from a master agent when a request is to be sent The only request an agent can send is Inform Request The net if process needs to remember the request id and the Pid and when a response is received for the request id send it to Pid using a snmp_response_received message Vsniseither version 1 version 2 OF version 3 Pduisan SNMP PDU record as defined in snmp_typeshrl with the SN MP response MsgData is the message specific data used in the SNMP message This value is normally sent to snmp_mpd generate_message 4 In SNMPv1 and SNM Pv2c this message data is the community string In SNM Pv3 it is the context information To isalist of the destination addresses and their corresponding security parameters This value is normally sent to snmp_mpd generate_message 4 Pid isa process identifier Notes Since the N et if process is responsible for encoding and decoding of SN M P messages it must also update the relevant counters in the SN MP group in MIB II It can use the functions in the module snmp_mpd for this purpose refer to the Reference M anual section sn
183. specify that the IP and port address should be reusable If false the agent the address is set to reusable Default is false snmp_agent_type master sub lt optional gt If master one master agent is started O therwise no agents are started D efault is master snmp config dir string lt mandatory gt Defines where the SN MP configuration files and the compiled master agent MIB files are stored snmp db_dir string lt mandatory gt Defines where the SN MP internal db files are stored Simple N etwork M anagement Protocol SN M P 99 snmp 100 SNMP Reference Manual snmp master_agent_mibs string lt optional gt Specifies a list of MIB names and defines which M IBs are initially loaded into the SN MP master agent These M IBs are loaded from snmp_config_dir snmpmulti_threaded bool lt optional gt If true the agent is multi threaded with one thread for each get request Default is false snmp_priority atom lt optional gt Defines the Erlang priority for all SNMP processes D efault isnormal vi bool lt optional gt Defines if the agent shall speak SN M Pv1 Default is true v2 bool lt optional gt Defines if the agent shall speak SN M Pv2c Default is true v3 bool lt optional gt Defines if the agent shall speak SN M Pv3 Default is true snmp_local_db_auto_repair false true true_verbose lt optional gt When starting snmp_local_db it always tries to open an existing database
184. t byte Types e Message message Encodes a message record to a list of bytes enc_message_only Message gt byteQ Types e Message message Message is arecord where the data field is assumed to be encoded a list of bytes If there is a v1 or v2 message the data field is an encoded PDU and if there is a v3 message data is an encoded and possibly encrypted scopedPDU enc_pdu Pd gt byte Types e Pdu pdu Encodes an SN MP Pdu into a list of bytes enc_scoped_pdu ScopedPdu gt byte 138 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_pdus Types e ScopedPdu scoped_pdu Encodes an SNMP ScopedPdu into a list of bytes which can be encrypted and after encryption encoded with a call to enc_encrypted_scoped_pdu 1 or it can be used as the data field in amessage record which then can be encoded with enc_message_only 1 enc_usm_security_parameters UsmSecParams gt byte Types e UsmSecParams usmSecurityParameters Encodes SN MP UsmSecurityParameters into a list of bytes Simple N etwork M anagement Protocol SN M P 139 snmp standard_mib SNMP Reference Manual snmp_standard_mib Erlang Module The module snmp_standard_mib implements the instrumentation functions for the STAN DARD MIB and SNM Pv2 MIB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Ty
185. t request processing so that new values can be checked for inconsistencies If the function is called it will be called again with undo or with set as first argument This function is optional Arguments e RowIndex is a list of integers which define the key values for the row The RowIndex is the list representation list of integers which follow the Cols integer in the OBJECT IDENTIFIER e Cols isa list of Column NewValue where Column is an integer and NewValue is guaranteed to be of the correct type length and within ranges as specified in the MIB If the object is an enumerated integer or of type BITS the integer value is used The list is sorted by Column increasing and each Column is guaranteed to be a valid column number Valid Return Values e noError 0 e Error Column where Error is the same as for is_set_ok for variables and Column denotes the faulty column Column must be one of the columns in the Cols list f undo RowIndex Cols ExtraArgs If an error occurs The fumction f undo RowIndex Cols ExtraArgs is called after the is_set_ok function If set is called for this object undo is not called This function is optional Arguments e RowIndex isa list of integers which define the key values for the row The RowIndex is the list representation list of integers which follow the Cols integer in the OBJECT IDENTIFIER e Cols isa list of Column NewValue where Column is an integer and NewVal
186. te store D efault is silence snmp_net_if_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP net if Default is silence snmp_mibserver_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SN MP mib server Default is silence snmpmib_storage ets dets Dir dets Dir Action mnesia Nodes mnesia Nodes Ac Specifies how info retrieved from the mibs will be stored D efault is ets Dir string Dir isthe directory where the dets files will be created Nodes node If Nodes then the own node is assumed Action clear keep Default iskeep Action is used to specify what shall be done if the mnesia table already exist See Also application 3 disk_log 3 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp snmp Erlang Module The module snmp contains interface functions to the SN MP toolkit Some functions are off line functions e g c to compile a MIB and some are functions called by instrumentation functions in a target system e g current_address Common Data Types The following datatypes are used in the functions below e oid byteO The oid type is used to represent an ASN 1 OBJECT IDENTIFIER Exports add_agent_caps SysORID SysORDescr gt SysORIndex Types e SysO RID oid e SysO RD escr string e SysO RIndex integer This function can
187. tes a complete index structure i e the ets table holding the index The index can no longer be referenced after this call See the warning note page 123 above delete Index Key gt NewIndex Types e Index NewIndex index e Key key D eletes a key and its value from the index structure Returns a new structure get Index Key0id gt ok Key0id Value undefined Types e Index index e KeyOid oid e Value term Gets the item with key Key0id Could be used from within an SN MP instrumentation function get_last Index gt ok Key0id Value undefined Types e Index index e KeyOid oid e Value term Gets the last item in the index structure get_next Index Key0id gt ok NextKey0id Value undefined Types e Index index e KeyOid NextKeyO id 0id e Value term Gets the next item in the SNMP lexicographic ordering after KeyOid in the index structure KeyOid does not have to refer to an existing item in the index insert Index Key Value gt NewIndex Types e Index NewIndex index e Key key e Value term Inserts a new key value tuple into the index structure If an item with the same key already exists the new Value overwrites the old value key_to_oid Index Key gt KeyQid Types e Index index 124 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_index e Key key e KeyOid NextKeyOid oid Converts Ke
188. th an error of inconsistentValue NOTE WELL A conceptual row having a status column with value notInService or notReady is unavailable to the managed device As such it is possible for the managed device to create its own instances during the time between the management protocol set operation which sets the status column to createAndWait and the management protocol set operation which sets the status column to active In this case when the management protocol set operation is issued to set the status column to active the values held in the agent supersede those used by the managed device If the management station is prevented from setting the status column to active e g due to management station or network failure the conceptual row will be left in the notInService or notReady state consuming resources 66 Simple N etwork M anagement Protocol SN M P SYNTAX 1 12 SNMP Appendix B indefinitely The agent must detect conceptual rows that have been in either state for an abnormally long period of time and remove them It is the responsibility of the DESCRIPTION clause of the status column to indicate what an abnormally long period of time would be This period of time should be long enough to allow for human response time including think time between the creation of the conceptual row and the setting of the status to active In the absense of such information in
189. the ASN 1 file is completed let the MIB compiler generate a default implementation and develop the management application from this 22 Simple N etwork M anagement Protocol SN M P 1 3 Instrumentation Functions Table Operations The generation of default functions for tables works for tables which use the RowStatus textual convention from SN M Pv2 defined in STANDARD MIB and SNM Pv2 TC N ote We strongly encourage the use of the RowStatus convention for every table that can be modified from the manager even for newly designed SN M Pv1 MIBs In SNM Pv1 everybody has invented their own scheme for emulating table operations which has led to numerous inconsistencies The convention in SN M Pv2 is flexible and powerful and has been tested successfully If the table is read only no RowStatus column should be used 1 3 4 Atomic Set In SNMP the set operation is atomic Either all variables which are specified in a set operation are changed or none are changed Therefore the set operation is divided into two phases In the first phase the new value of each variable is checked against the definition of the variable in the MIB The following definitions are checked e thetype e the length e the range e the variable is writable and within the MIB view At the end of phase one the user defined is_set_ok functions are called for each scalar variable and for each group of table operations If no error occurs the second phase is pe
190. the intTrapDestTable from OTP SN M PEA MIB There are a few new functions in the module snmp for trap notification sending Two new modules are added snmp_notification_mib and snmp_target_mib These modules contain functions for initialising the agent data from configuration files There is anew function reconfigure 1 in snmp_standard_mib which reconfigures the persistent objects from the configuration files The following mibs are added to the distribution for completeness SNM Pv2 TM SNM Pv2 SM SNM Pv2 CONF SNMP FRAMEWORK MIB RFC1155 SM RFC 1212 RFC 1215 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions The snmp_mgr no longer crashes if an unknown trap is received Own Id OTP 2137 OT P 2464 The supervisor of the mibs has a correct shutdown time infinity instead of 2 secs Own Id OTP 2310 Aux Id seq767 HA79462 The Mib Compiler now handles the construct MODULE OtherM odule in the MODULE COMPLIANCE macro Own Id OTP 2465 The Mib Compiler now handles the construct INTEGER 0 1 3 4 Own Id OTP 2466 The Mib Compiler now handles IM PLIED OIDs Own Id OT P 2467 The Mib Compiler now handles REFERENCE in the OBJECT IDENTITY macro Own Id OT P 2468 Incompatibilities with v2 1 1 e The table intTrapDestTable in OT P SN M PEA MIB is not used anymore e There are three new configuration files target_addr conf target_params
191. tion file will have StorageType nonVolatile Thus the data in the SN MP TARGET MIB after this function has been called is the data from the configuration files All snmp counters are set to zero If an error is found in the configuration file it is reported using the function config_err 2 of the and the function fails with the reason configuration_error ConfDir isa string which points to the directory where the configuration files are found The configuration files read are target_addr conf and target_params conf 144 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_target_mib set_target_engine_id TargetAddrName EngineId gt boolean Types e TargetA ddrN ame string e Engineld string Changes the enigne id for a target in the snmpTargetAddrTable If notifications are sent as Inform requests to a target its engine id must be set Simple N etwork M anagement Protocol SN M P 145 snmp_user_based_sm_mib SNMP Reference Manual snmp_user_based_sm_mib Erlang M odule The module snmp_user_based_sm_mib implements the instrumentation functions for the SN M P U SER BA SED SM M IB and functions for configuring the database The configuration files are described in the SN MP User s M anual Exports configure ConfDir gt void Types e ConfDir string This function is called from the supervisor at system start up Inserts all data in the configuration files into the database and
192. tion of sub trees MIB View Semantics An MIB view isa collection of included and excluded sub trees A sub tree is identified by an OBJECT IDENTIFIER A mask is associated with each sub tree For each possible MIB object instance the instance belongs to a sub tree if e the OBJECT IDENTIFIER name of that M IB object instance comprises at least as many sub identifiers as does the sub tree and e each sub identifier in the name of that MIB object instance matches the corresponding sub identifier of the sub tree whenever the corresponding bit of the associated mask is 1 0 isa wild card that matches anything Membership of an object instance in an MIB view is determined by the following algorithm e If an MIB object instance does not belong to any of the relevant sub trees then the instance is not in the MIB view e If an MIB object instance belongs to exactly one sub tree then the instance is included in or excluded from the relevant M IB view according to the type of that entry e f an MIB object instance belongs to more than one sub tree then the sub tree which comprises the greatest number of sub identifiers and is the lexicographically greatest is used Simple N etwork M anagement Protocol SN M P 13 Chapter 1 SNMP User s Guide N ote If the OBJECT IDENTIFIER is longer than an OBJECT IDENTIFIER of an object type in the M IB it refers to object instances Because of this it is possible to control whether or not particula
193. twork M anagement Protocol SN M P 1 2 Functional Description 1 2 Functional Description The SN MP development toolkit contains the following parts e An Extensible multi lingual SN MP agent which understands SN M Pv1 RFC 1157 SN M Pv2c RFC 1901 1905 1906 and 1907 SNM Pv3 RFC2271 2272 2273 2274 and 2275 or any combination of these protocols e A MIB compiler which understands SM Iv1 RFC 1155 1212 and 1215 and SM Iv2 RFC 1902 1903 and 1904 e A multi lingual SN MP manager which can be used for simple interactive testing and for writing test suites The SNMP agent system consists of one M aster Agent and optional Subagents The tool makes it easy to dynamically extend an SN MP agent in runtime M IBs can be loaded and unloaded at any time It is also easy to change the implementation of an MIB in runtime without having to recompile the MIB The MIB implementation is clearly separated from the agent To facilitate incremental M IB implementation the tool can generate a prototype implementation for a whole M IB or parts thereof This allows different MIBs and management applications to be developed at the same time 1 2 1 Definitions The following definitions are used in the SNMP User s Guide MIB The conceptual repository for management information is called the M anagement Information Base M IB It does not hold any data merely a definition of what data can be accessed A definition of an MIB is a desc
194. ue is guaranteed to be of the correct type length and within ranges as specified in the MIB If the object is an enumerated integer or of type BITS the integer value is used The list is sorted by Column increasing and each Column is guaranteed to be a valid column number Valid Return Values e noError 0 e Error Column where Error is the same as for undo for variables and Column denotes the faulty column Column must be one of the columns in the Cols list f set RowIndex Cols ExtraArgs The fumction f set RowIndex Cols ExtraArgs is called to perform the set in phase two of the set request processing It is only called if the corresponding is_set_ok function did not exist or returned noError O This functionn is mandatory 54 Simple N etwork M anagement Protocol SN M P 1 10 Definition of Net if Arguments e RowIndex isa list of integers that define the key values for the row The RowIndex is the list representation list of integers which follow the Cols integer in the OBJECT IDENTIFIER e Cols iS alist of Column NewValue where Column is an integer and NewValue is guaranteed to be of the correct type length and within ranges as specified in the MIB If the object is an enumerated integer or of type BITS the integer value is used The list is sorted by Column increasing and each Column is guaranteed to be a valid column number Valid Return Values e noError 0 e Error Column where Er
195. unction returns according to the specification of an instrumentation function variable_get NameDb gt value Value undefined Types e Value term Gets the value of a variable variable_set NameDb NewVal gt true false Types 120 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _generic e NewVal term Sets a new value to a variable The variable is created if it does not exist No checks are made on the type of the new value Returns false if the NameDb argument is incorrectly specified otherwise true Example The following example shows an implementation of a table which is stored in M nesia but with some checks performed at set request operations myTable_func new NameDb gt pass unchanged snmp_generic tablefunc new NameDb myTable_func delete NameDb gt pass unchanged snmp_generic tablefunc delete NameDb A change row myTable_func is_set_ok RowIndex Cols NameDb gt case snmp_generic table_func is_set_ok RowIndex Cols NameDb of noError 0 gt myApplication is_set_ok RowIndex Cols Err gt Err end myTable_func set RowIndex Cols NameDb gt case snmp_generic table_func set RowIndex Cols NameDb noError 0 gt Now the row is updated tell the application myApplication update RowIndex Cols Err gt Err end myTable_func Op RowIndex Cols NameDb gt pass unchanged snmp_generic table_func Op RowIndex Col
196. untime e to provide interaction with other SN MP agent toolkits Refer to the chapter Advanced Topics page 39 in this User s Guide for more information about these topics The communication protocol between subagents is the normal message passing which is used in distributed Erlang systems This implies that subagent communication is very efficient compared to SMUX DPI AgentX and similar protocols 8 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description 1 2 6 Contexts and Communities A context is a collection of management information accessible by an SNMP entity An instance of a management object may exist in more than one context An SNMP entity potentially has access to many contexts Each managed object can exist in many instances within aSNMP entity To identify the instances specified by an MIB module a method to distinguish the actual instance by its scope or context is used O ften the context is a physical or a logical device It can include multiple devices a subset of a single device or a subset of multiple devices but the context is always defined as a subset of a single SNMP entity To be able to identify a specific item of management information within an SNMP entity the context the object type and its instance must be used For example the managed object type ifDescr from RFC 1573 is defined as the description of a network interface To identify the description of device X s first net
197. use the same U DP port the agent that starts last will completely control the port The reason for this is that the UDP port is opened with a reuse directive A new option no_reuse_address which if set causes the reuse directive not to be set Own Id OTP 3317 Aux Id seq4008 Simple N etwork M anagement Protocol SN M P 75 Chapter 1 SNMP User s Guide Debug printouts from snmp_net_if appeared even when the debug flag was not set This has been corrected O wn ld OTP 3345 Aux Id seq4091 1 13 16 SNMP Development Toolkit v3 1 1 Improvements and new features The audit trail log has been improved N ow each log item also contains a time stamp Also the text format of a log produced by a call to snmp 1og to_txt has been changed to be more line oriented The function snmp log_to_txt 4 has been added Own Id OTP 3261 Aux Id seq3884 OTP 3253 Each item in an audit trail text log file produced by snmp log_to_txt now has a trailing TAB character and any TAB character in the body of a text item is replaced by ESC TAB Own Id OTP 3282 Aux Id seq3969 The function snmp log_to_txt 5 has been added so that not only the log name but also the log file name can be specified when converting an audit trail log to text format Own Id OTP 3298 Aux Id A new optional environment variable bind_to_ip_addess has been added controlling if the agent should bind to the specific IP address or not Own Id OTP 3293 Aux
198. value upstairs in the trap we could use one of e sysLocation upstairs or e 1 3 6 1 2 1 1 6 0 upstairs or e sysLocation_instance upstairs provided that the generated hr1 file is included If a variable in the trap is a table element the RowIndex for the element must be given in the Varbinds list In this case the OBJECT IDENTIFIER sent in the trap is the OBJECT IDENTIFIER that identifies this element This OBJECT IDENTIFIER could be used in a get operation later This function is asynchronous and does not return any information If an error occurs snmp_error user_err 2 is called and the trap is discarded universal_time_to_date_and_time UTC gt DateAndTime Types e UTC Y Mo D H M S e DateAndTime int Converts a universal time value to a DateAndTime list The unversal time value on the same format as defined in calendar 3 unload mibs Agent Mibs gt ok error Reason Types e Agent pid atom e Mibs MibN ame Simple N etwork M anagement Protocol SN M P 111 snmp SNMP Reference Manual e MibName string Unloads MIBs into an agent If it cannot unload all MIBs it will indicate where unloading was aborted unregister_subagent Agent Subagent0idOrPid gt ok ok SubAgentPid error Reason Types e Agent pid atom e SubTreeO idorPid oid pid Unregisters a subagent If the second argument is a pid then that subagent will be unregistered
199. velopment Toolkit v2 0 0 oo ee 83 1 13 30SNMP Development Toolkit v1 3 0 ooo 84 1 13 31SNMP Development Toolkit v1 3 o 0 oo o 84 1 13 32SNMP Development Toolkit v1 2 o ooo 85 1 13 333N MP Development Toolkit v1 2 0 o oo o 86 Simple N etwork M anagement Protocol SN M P Vv 2 SNMP Reference Manual 2 1 A NR O ee ees 2 2 el E Ay ah EEE tee ten E Ae Gh ashy Styl dala Go ehh 2 3 sAMP COMMUNIEYAMID vu ip oe oe a hg fede Pe ie PA OS EO 2 4 SAMPLE fot eae aries A RS A eae Ee ae cae A 2 5 SAMPANO Or rias tna a th Uh hs Gs RAP aR ere te Me decide le eae hath we de dot 2 6 Mp error TERO ee ll ak Go i a a aha ahah A end ee Bae ee a 2 7 snmp framework mib vii a ee ee le eh 2 8 SAMPzGENETIC oc a kha e Ree ARES AA ae ae 2 9 SMIMPSING OK Ltda AO a Ai aah ah ch ahem A facta de he Ode ie hk a ZAOe gt nmpalocal Dias a BAG a E oe nes Aime A sara 2E PMR Vert AAA A a a A A na a aa ARS 212 Mp MPA estie rc e de OA ee eE ES 2 137 shMpnotificatiOn MID vy css ee rinitis we E 214 SMPPA S ria e A RAR ees A oa i 2 15 snmp standard mib o o o 2 16 snmp _supervisor 2 17 snmp_target_mib 2 18 snmp user based sm mib 2 o o e 2 19 snmp_view_based_acM_Mib o e e List of Figures List of Tables Simple N etwork M anagement Protocol SN M P 89 99 101 113 114 115 116
200. w 2 snmp_local_db 128 table_exists 1 snmp_local_db 128 table_func 2 snmp generic 119 table_func 4 snmp generic 119 table_get_elements 3 snmp generic 120 table_get_row 2 snmp_local_db 128 table_next 2 snmp generic 120 table_row_exists 2 snmp generic 120 table_set_elements 3 snmp generic 120 universal_time_to_date_and_time 1 snmp 111 unload_mibs 2 snmp 111 unregister_notify_client 1 snmp_local_db 128 unregister_subagent 2 snmp 112 user_err 2 snmp error 114 snmp error_io 115 snmp_error_report 116 validate_date_and_time 1 snmp 112 Simple N etwork M anagement Protocol SN M P 157 Index of Modules and Functions variable_func 2 snmp generic 120 variable_func 3 snmp generic 120 variable_get 1 snmp generic 120 variable_set 2 snmp generic 120 verbosity 2 snmp 112 158 Simple N etwork M anagement Protocol SN M P
201. which communicates through a protocol specified by the other package 1 7 2 Agent Semantics The agent can be configured to be multi threaded or to process one incoming request at atime If it is multi threaded read requests get get next and get bulk and traps are processed in parallel with each other and set requests H owever all set requests are serialized which means that if the agent is waiting for the application to complete a complicated write operation it will not process any new write requests until this operation is finished It processes read requests and sends traps concurrently The reason for not parallelize write requests is that a complex locking mechanism would be needed even in the simplest cases Even with the scheme described above the user must be careful not to violate that the set requests are atoms If this is hard to do do not use the multi threaded feature The order within an request is undefined and variables are not processed in a defined order Do not assume that the first variable in the PDU will be processed before the second even if the agent processes variables in this order It cannot even be assumed that requests belonging to different subagents have any order If the manager tries to set the same variable many times in the same PD U the agent is free to improvise There is no definition which determines if the instrumentation will be called once or twice If called once only there is no definition that
202. work interface four pieces of information are needed the snmpEnginelD of the SNMP entity which provides access to the management information at device X the contextName device X the managed object type ifDescr and the instance 1 In SNM Pv1 and SNM Pv2c the community string in the message was used for at least three different purposes e to identify the context e to provide authentication e to identify a set of trap targets In SNM Pv3 each of these usage areas has its own unique mechanism A context is identified by the name of the SN MP entity contextEnginelD and the name of the context contextName Each SN MPv3 message contains values for these two parameters ThereisaMIB SNMP COMMUNITY MIB which maps a community string to a contextEngineID and contextName Thus each message an SNM Pv1 SN MPv2c or an SN MPv3 message always uniquely identifies a context For an agent the contextEnginelD identified by a received message is always equal to the snmpEnginelD of the agent O therwise the message was not intended for the agent If the agent is configured with more than one context the instrumentation code must be able to figure out for which context the request was intended There is a function snmp current_context 0 provided for this purpose By default the agent has no knowledge of any other contexts than the default context If it is to support more contexts these must be explicitly added by using an a
203. x int Sends the notification Notification to the management targets defined for NotifyName in the snmpNotifyTable in SNMP NOTIFICATION MIB from the specified context If no NotifyName is specified or if it is the notification is sent to all management targets If no ContextName is specified the default context is used The parameter Receiver specifies where information about delivery of Inform Requests should be sent The agent sends Inform R equests and waits for acknowledgements from the managers If the Receiver is specified as no_receiver nothing is sent O therwise it is specified as Tag Recv The receiver Recv gets a message e snmp_targets Tag Addresses Simple N etwork M anagement Protocol SN M P 109 snmp SNMP Reference Manual Addresses isa list of management target addresses If UDP over IP is used this is a 2 tuple IP UDPport where IP is a 4 tuple with the IP address and UDPport is an integer The notification is sent as an Inform Request to each target address in Addresses If there are no targets for which an Inform Request is sent Addresses is the empty list For each such Address is the Addresses list one of the following two messages is sent to Recv e snmp notification Tag got_response Address e snmp notification Tag no_response Address The optional argument Varbinds defines values for the objects in the notification If no value is given for an object the Agent pe
204. xample illustrates this idea emp_table set RowIndex Cols gt notify_internal_resources RowIndex Cols snmp_generic table_func set RowIndex Cols fempTable mnesia emp_table Op RowIndex Cols gt snmp_generic table_func Op RowIndex Cols empTable mnesia The default instrumentation functions are defined in the module snmp_generic Refer to the Reference M anual section SN M P module snmp_generic for details Extending the Mnesia Table A table may contain columns that are used internally but should not be visible to a manager These internal columns must be the last columns in the table The set operation will not work with this arrangement because there are columns that the agent does not know about This situation is handled by adding values for the internal columns in the set function To illustrate this suppose we extend our M nesia empTable with one internal column We create it as before but with an arity of 4 by adding another attribute mnesia create_table name employees snmp key integer string attributes key telno row_status internal_col The last column is the internal column When performing a set operation which creates a row we must give a value to the internal column The instrumentation functions will now look as follows 44 Simple N etwork M anagement Protocol SN M P 1 7 Advanced Topics define createAndGo 4 define createAndWait 5 emp_table set R
205. y to an OBJECT IDENTIFIER new KeyTypes Types e KeyTypes key_types Creates a new snmp index structure The key_types type is described above Simple N etwork M anagement Protocol SN M P 125 snmp local_db SNMP Reference Manual snmp_local_db Erlang Module The module snmp_local_db contains functions for implementing tables and variables using the SNMP built in database The database exists in two instances one volatile and one persistent The volatile database is implemented with ets The persistent database is implemented with a module pets Persistent ets Erlang Term Store that keeps an ets database in memory for speed and on disk for persistent storage At start up the ets database is initialized from disk All readings from the database go to the ets Writings go also to the ets and a note is made in a log file When the database is closed the entire ets database is dumped and the log file is cleared If a crash occurs the log file will always contain the latest changes At start up the dumped ets is read and then the database is recovered using the log file It is also possible to manually dump the database in which case the entire ets is dumped and the log file is cleared There are three scaling problems with this database e If the database is never dumped there are a lot of modifications to the database and the log file will grow rapidly This can be solved by regularly dumping the database e The s

Simple Network Management Protocol (SNMP)

Contents

Download Pdf Manuals

Related Search

Related Contents