Home

Simple Network Management Protocol (SNMP)

1. snmp local db Mnesia Database l dets l Persistent storage Each function takes the argument NameDb which is a tuple Name Db to identify which database the functions should use Name is the symbolic name of the managed object as defined in the MIB 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 SN MP table The SN MP tables are stored in M nesia tables with the same names as the SN MP tables AIl 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 And for a table Simple N etwork M anagement Protocol SN M P 117 snmp _generic SNMP Reference Manual 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 RowInde
2. delete_sec2group Key gt Ret Types e Key term e Ret ok error Reason e Reason term D elete a security to group definition from the agent config add_access GroupName Prefix SecModel SecLevel Match RV WV NV gt Ret Types e GroupN ame string e Prefix string e SecM odel v1 v2c usm SecL evel string e Match prefix exact e RV string e WV string e NV string e Ret ok Key error Reason e Key term e Reason term Adds a access definition to the agent config Equivalent to one vacmA ccess line in the vacm conf file delete_access Key gt Ret Types e Key term e Ret ok error Reason e Reason term D elete a access definition from the agent config add_view_tree_fam ViewIndex SubTree Status Mask gt Ret Types e ViewIndex integer 150 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _view_based_acm_mib e SubTree oid e Status included excluded e Mask null integer where all values are either 0 or 1 e Ret ok Key error Reason e Key term e Reason term Adds a view tree family definition to the agent config Equivalent to one vacmV iewTreeFamily line in the vacm conf file delete_view_tree_fam Key gt Ret Types e Key term e Ret ok error Reason e Reason term Delete a view tree family definition from the agent config Simple N etwork M anagement Proto
3. Col NewVal T gt merge_rows setelement Col Row 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 ex1 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 hh 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 snmp_mgr start_link agent dront ericsson se community public hh does not have write acce
4. Erlang M odule snmp _standard_mib page 140 Instrumentation Functions for STAN DARD 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 TA RG ET M IB Erlang M odule snmp_user_based_sm_mib page 147 Instrumentation Functions for SNM P U SER BA SED SM M IB Erlang M odule snmp_view_based_acm_mib page 149 Instrumentation Functions for SN M P VIEW BASED ACM MIB Simple N etwork M anagement Protocol SN M P 85 SNMP Reference M anual snmp No functions are exported snmp The following functions are exported e add_agent_caps SysORID SysORDescr gt SysORIndex page 98 Add an AGENT CAPABILITY definition to the agent e c File page 98 Compile the specified MIB e c File Options gt ok BinFileName error Reason page 98 Compile the specified MIB change_log_size NewSize gt ok error Reason page 99 Change the size of the Audit Trail Log config gt ok error Reason page 99 Configurate with a simple SNM P agent configuration tool e current_address gt value IP UDP false page 100 Retrieve the IP address of the manager e current_community gt value Community false page 100 Retrieve the community of the current request e current_context gt value ContextName false page 100 Retrieve the context of the current requ
5. From delete_row RowIndex gt NewTable table_delete_row Table RowIndex Name NewTable _row NewRow gt e table_add_row Table NewRow Name NewTable loop My From add NewTabl loop My end IN hhh Functions for table operations The table is represented as a list of rows lalola Ae os 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 ok 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 O 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
6. See Also application 3 disk_log 3 Simple N etwork M anagement Protocol SN M P 97 snmp SNMP Reference Manual 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 oidQ byte The oid type is used to represent an ASN 1 OBJECT IDENTIFIER Exports add_agent_caps SysORID SysORDescr gt SysORIndex c File Types e SysORID oid e SysO RD escr string e SysO RIndex integer This function can 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 Options gt ok BinFileName error Reason 98 Types e File string e Options opt e opt db volatile persistent mnesia i dir 1 il dir 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 SNMP Reference Manual snmp The option db specifies which
7. 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 or snmpmnotification Tag no_response ManagerAddr for each management target Sometimes it is not possible to retrieve the values
8. e DateAndTime int Converts a local time value to a list of possible D ateA ndTime list s 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 error 104 Reason Types e LogDir string e Mibs MibN ame e OutFile string e MibN ame string e LogN ame 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 replaced by ESC TAB The function can be used on a running system or by copying the entire log directory and calling this function SN MP must be running in order to provide MIB 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 M ibs to convert for example object identifiers to their symbolic name OutFile is the name of the generated textfile It defaults to snmp_log txt
9. e the basics of the Simple N etwork Management Protocol version 1 SN M Pv1 e the basics of the community based Simple Network M anagement Protocol version 2 SN M Pv2c e the basics of the Simple N etwork M anagement Protocol version 3 SNM Pv3 e the knowledge of defining MIBs using SMIv1 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 SNMP User s Guide contains the following chapters Chapter 2 Functional Description describes the features and operation of the SNMP 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 Agent 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 M IB can be implemented with the SNMP Development Toolkit Implementation examples are included Chapter 7 Advanced Topics describes subagents agent semantics audit trail logging and the consideration of distributed t
10. MasterAgent gt isa Pid Args s a a list of arguments e net_if_verbosity silence info log debug trace A description of verbosity can be found here page 109 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 isa 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 Net 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 OF version 3 Pdu s an SNMP PDU record as defined in snmp_types hri1 with the SNMP request PduMs is the Maximum 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 M odule in use Normally this is returned from snmp_mpd process_packet see Reference M anual From is the source address If UDP over IP is used this should be a 2 tuple IP UDPport where IP isa 4 tuple with the 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 t
11. SNMP Reference Manual snmp_mpd snmp_mpd Erlang M odule 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 initmpd 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 e TDomain snmpUD PD omain e TAddress Ip U dp e Ip integer integer integer integer e Udp integer e State mpd_state e Vsn version 1 version 2 version 3 e Pdu odu e PduMs integer e ACM Data acm_data Processes an incoming packet Performs authentication and decryption as necessary The return values should be passed the agent generate_response_msg Vsn RePdu Type ACMData gt ok Packet discarded Reason Types e Vsn version 1 version 2 version 3 e RePdu odu Simple N etwork M anagement Protocol SN M P 133 snmp_mpd SNMP Reference M anual 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
12. SYNTAX SEQUENCE OF EmpEntry ACCESS not accessible STATUS mandatory DESCRIPTION A table with information about employees emp 1 empEntry OBJECT TYPE SYNTAX EmpEntry ACCESS not accessible STATUS mandatory DESCRIPTION INDEX empDepNo empName empTable 1 EmpEntry SEQUENCE 4 empDepNo INTEGER empName DisplayString empTelNo DisplayString empStatus RowStatus 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 Mnesia API to access the table from your programs The only explicit action is to create the Mnesia 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
13. e opt mibs Mibs net_if N etlfM odule priority Prio name Name e Mibs MibN ame e MibName string 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 STANDARD MIB is not specified in the Mibs list it is loaded from the configuration directory i e with the conf files If no Net IfModules is specified the default net if implementation is used snmp_net_if Prio isan Erlang priority All SN MP processes use this priority D efault 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 MibName 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
14. exists and that a row which isto be created does not exist The undo function does nothing The set function checks if it has enough information to make the row change its status from notReady to notInService when a row has been been set to createAndWait If arow is set to createAndWait columns without a value are set to noinit If M nesia is used the set functionality is handled within a transaction 118 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp generic If it is possible for a manager to create or delete rowsin the table there must be a 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 Rest0id gt RowIndex endOfTable Types e RestO id int Finds the indices of the next row in the table Rest0id does not have to specify an existing row table_row_exists NameDb RowIndex gt bool Checks if a row in a table 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 mnesia write to store the values This means that t
15. manager It is recommended to use the SN M Pv2 error codes for all instrumentation functions as these provide more details See A ppendix 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 Rowlndex 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 sa 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 anagement 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
16. page 130 Send N get next request requests rQ gt void page 130 Resend the last request oid_to_name 0id gt ok Name error Reason page 130 Transform a oid to it s aliasname name_to_oid Name gt ok Oid error Reason page 130 Transform a aliasname to it s oid s Varbinds gt void page 130 Send a set request start Options page 130 Start the SN MP manager start_link Options gt void page 131 Start the SN MP manager stop gt void page 132 Stop the SN MP manager Simple N etwork M anagement Protocol SN M P 91 SNMP Reference Manual snmp_mpd The following functions are exported e init_mpd Options gt mpd_state page 133 Initialize the MPD module process_packet Packet TDomain TAddress State gt ok Vsn Pdu PduMS ACMData discarded Reason page 133 Process a packet received from the network generate_responsemsg Vsn RePdu Type ACMData gt ok Packet discarded Reason page 133 G enerate a response packet to be sent to the network generate msg Vsn Pdu MsgData To gt ok PacketsAndAddresses discarded Reason page 134 Generate a request message to be sent to the network discarded_pdu Variable gt void page 134 Increment the variable associated with a discarded pdu snmp_notification_mib The following functions are exported e configure ConfDir gt void page 135 Configure the SNMP NOTIFICATION MIB e
17. 140 142 144 147 149 153 155 Chapter 1 SNMP User s Guide A multilingual Simple N etwork Management Protocol Extensible A gent featuring a MIB compiler and facilities for implementing SN MP MIBs etc 1 1 SNMP Introduction TheSNMP 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 M anagement Information Base M IB in Abstract Syntax N otation O ne ASN 1 e instrumentation functions for the managed objects in the M IB 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 Development Environment which is described in a separate User s G uide 1 1 2 Prerequisites The following prerequisites is required for understanding the material in the SNMP User s Guide
18. 144 Configure the SN MP TARGET MIB e set_target_engine_id TargetAddrName EngineId gt boolean page 145 Set the engine id for a targetA ddr row e add_addr Name Ip Port Timeout Retry TagList Params Engineld TMask MMS gt Ret page 145 Add one target address definition delete_addr Key gt Ret page 145 Delete one target address definition add_params Name MPModel SecModel SecName SecLevel gt Ret page 145 Add one target parameter definition delete_params Key gt Ret page 146 Delete one target parameter definition snmp_user_based_sm_mib The following functions are exported e configure ConfDir gt void page 147 Configure the SN M P U SER BA SED SM M IB e reconfigure ConfDir gt void page 147 Configure the SN M P U SER BA SED SM M IB add_user EngineID Name SecName Clone AuthP AuthKeyC OwnAuthKeyC PrivP PrivKeyC OwnPrivKeyC Public AuthKey PrivKey gt Ret page 148 Add one user delete_user Key gt Ret page 148 Delete one user snmp_view_based_acm_mib The following functions are exported e configure ConfDir gt void page 149 Configure the SNM P V IEW BA SED ACM M IB e reconfigure ConfDir gt void page 149 Configure the SN M P V IEW BA SED AC M M IB e add_sec2group SecModel SecName GroupName gt Ret page 150 Add one security to group definition e delete_sec2group Key gt Ret page 150 Delete one security to grou
19. Aleynikov Own Id OTP 4810 agent Code up downgrade cleanup Own Id OTP 4811 compiler Fixed a parser error that caused the group checks to behave erratic Also fixed related group check problems which among other things produced cryptic error messages Own Id OTP 4825 Aux Id Seg 8183 1 13 13 SNMP Development Toolkit v3 4 Version 3 4 0 supports code replacement in runtime from to version 3 3 8 Improvements and new features agent MIB server has been re written to improve memory usage It is now also possible to create the mib database before starting the snmp agent instead of loading mibs at runtime M IB data is stored in either ets default dets or mnesia Own Id OTP 4601 agent The snmp_local_db now use dets for persistent storage instead of snmp_pets Own Id OTP 4720 74 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions compiler Added check and warning for sloppy asignment in MIBs Own Id OT P 4660 compiler Fixed a bunch of errors related to group checks Own Id OT P 4607 Aux Id Seg 7765 1 13 14 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 In case 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 Seg 7594 e SNMP mib compiler warning s cleanup Some of the w
20. 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 SNMP NOTIFICATIO N M IB after this function has been called isfrom the configuration files 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 addnotify Name Tag Type gt Ret Simple N etwork M anagement Protocol SN M P 135 snmp not
21. 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 SNMP Reference Manual snmp mib_to_hrl MibName gt ok error Reason Types e MibN ame string Generates a hr1 file with definitions of Erlang constants 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 OBJECT IDENTIFIER of a MIB object given the symbolic name Note the OBJEC
22. 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 SNM 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 the type 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 performed 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 pha
23. 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 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 inc
24. SNMP MPD MIB TheSNMP FRAMEWORK MIB and SNMP MPD MIB 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 M IBs 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 MIBs 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 nonVolatile Should the agent restart all nonVolatile rows survive the restart while the volatile rows are lost The configuration files a
25. a security model specific decoding function e g dec_usm_security_parameters 1 Also note if the scopedPDU is encrypted the OCTET STRING encoded encryptedPDU will be present in the data field dec_message_only byte gt Message Types e Message message Decodes a list of bytes into an SNMP Message but does not decode the data part of the Message 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 SN MP 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 a list of bytes dec_usm_security_parameters byte gt UsmSecParams Types e UsmSecParams usmSecurityParameters D ecodes 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 wi
26. 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 MIB II which is defined in RFC1213 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 SN MP 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 One of these M IBs is always loaded If only SN M 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 STAN DARD MIB three data types are defined RowStatus TruthValue and DateAndTime These data types are originally defined as textual conventions in SNM Pv2 TC RFC1903 SNMP FRAMEWORK MIB and
27. allows different kinds of subagents at the same time Accordingly different MIBs 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 However a subagent can be used on each node if this generates too much unnecessary traffic A subagent processes requests per incoming SNMP 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 M P 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 MIBs 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 MIBs each time This is cheaper than loading an MIB Interaction With Other SNMP Agent Toolkits If the SNMP agent needs to interact with subagents constr
28. 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 M IB 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 M IB into an existing subagent It is not necessary to create a new process for handling a new M IB 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 M IBs in runtime e to provide interaction with other SN MP agent toolkits Refer to the chapter Advanced Topics page 39 in this User
29. 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 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 Bs 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 Types e Row Vall Val2 ValN e Vall Val2 ValN term Creates a row in atable Row is a tuple with values for all columns including the index columns 126 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_local_db table_delete NameDb gt void D eletes a table table_delete_row NameDb RowIndex gt bool D eletes the row in the table table_exists NameDb gt bool Checks if a table exists table_get_row Name
30. conf files N ote that if the agent shall support version 3 then the crypto app must be started before running this function password generation 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 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_ifdata 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
31. 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 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 SN MPv2 MIB after this function has been called is from the configuration files All snmp counters are set
32. down to the pre defined function The following example illustrates this idea emp_table set RowIndex Cols gt notify_internal_resources RowIndex Cols snmp_generic table_func set RowIndex Cols empTable 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 MP 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 f 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 createAndG
33. 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 SNM 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 eg 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 ora get bulk request refers to the table The RowIndex argument may refer to an existing row or anon 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 instance is determined and the last part of its OBJECT IDENTIFIER and its value is returned This function is mandatory Arguments e RowIndex isa list of integers possibly empty that defines the key value
34. exist It does not destroy any old values add_context Ctx gt Ret Types e Ctx string e Ret ok Key error Reason e Key term e Reason term Adds a context to the agent config Equivalent to one line in the context conf file delete_context Key gt Ret Simple N etwork M anagement Protocol SN M P 115 snmp framework_mib SNMP Reference Manual Types e Key term e Ret ok error Reason e Reason term D elete a context from the agent config 116 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _generic snmp_generic Erlang M odule 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 SNMP Agent MIB Association file associates a MIB object with snmp_generic table_funct snmp generic variable func snmp generic Support for get next l RowStatus operations
35. from to version 3 4 9 3 4 8 3 4 7 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent Error replies was composed with invalid OIDs for the following error counters usmStatsW rongD igests RFC 2574 chap 3 2 point 6 usmStatsU nsupportedSecL evels point 5 and usmStatsD ecryptionErrors point 8a Own Id OTP 5464 Aux Id Seq 9791 agent Malformed O id returned from a get_next operation as part of a get bulk request causes the agent to crash Own Id OTP 5465 Aux Id Seq 9783 Seq 9793 Incompatibilities 1 13 4 SNMP Development Toolkit v3 4 9 Version 3 4 9 supports code replacement in runtime from to version 3 4 8 3 4 7 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Simple N etwork M anagement Protocol SN M P 69 Chapter 1 SNMP User s Guide Reported Fixed Bugs and Malfunctions agent Added missing type check for access simpC ommunityTable with is_set_ok Own Id OTP 4978 Aux Id Seq 8380 compiler Added default value for INTEGER with enumeration without a DEFVAL clause The lowest valid integer value is choosen for the variable_info defval Own Id OTP 5124 Aux Id Seq 8738 Incompatibilities 1 13 5 SNMP Development Toolkit v3 4 8 Version 3 4 8 supports code replacement in runtime from to version 3 4 7 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fix
36. function fails with the reason badarg stop_subagent SubAgent gt ok no_such_child Types e SubA gent pid 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 MP TARGET MIB and functions for configuring the database The configuration files are described in the SNMP 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 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
37. 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 ExtraArg1 For tables table_access set RowIndex Cols ExtraArgl1 Cols isa list 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 ExtraArgl1 For tables table_access set RowIndex Cols ExtraArgl1 Cols is alist of tuples Column NewValue GetNext Operation The GetNext 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 ExtraArgl Cols isa list of integers all greater than or equal to zero This indicates that the instrumentation should find the next accessible instance This function returns the tuple NextOid NextValue or endOfTable Next0id should be the lexicographically next accessible instance of a managed object in the t
38. 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 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 113 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 112 which still is the default and module snmp _error_io page 113 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 For
39. gt snmpmgr gn 1 3 6 1 3 7 ok Got PDU myName 0 hh A set request now using symbolic names for convenience 3 gt snmpmgr s myName 0 Martin ok gt A AA Got PDU myName 0 Martin hh Try the same get next request again 4 gt snmp mgr gn 1 3 6 1 3 7 ok Got PDU myName 0 Martin hh and we got the new value you can event do row operations How to add a row 5 gt snmpmgr s fName 0 Martin fAddress 0 home fStatus 0 4 createAndGO SS ok Got PDU fName 0 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 rows in the table friendsTable Each row is a 4 tuple Note 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 exports e
40. 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 l set status linconsistent linconsist noError noError column to Value entValue active l l or l lsee 2 gt DI gt D gt D set status linconsistent inconsist noError InoError gt C column to Value entValue notInService l or or l lsee 3 gt Cl gt C wrongValue set status noError noError noError noError column to destroy gt Al gt Al gt Al gt A set any other see 4 noError noError see 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 provide values for all columns which are missing but required then return noError and goto D
41. 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 122 Types e Index NewIndex index e Key key Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp index Deletes 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 122 above delete Index Key gt NewIndex Types e Index N ewlndex index e Key key Deletes a key and its value from the index structure Returns a new structure get Index Key0id gt ok KeyOid Value undefined Types e Index index e KeyOid oid e Value term Gets the item with key KeyOid Could be used from within an SN MP instrumentation function get_last Index gt ok KeyOid Value undefined Types e Index index e KeyOid 0id e Value term Gets the last item in the index structure get_next Index Key0id gt ok NextKeyDid Value undefined Types e Index index e KeyOid NextKeyO id oid e Value term Gets the next item in the SN MP lexicographic ordering after Key0id in the index structure KeyOid does not have
42. 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 Simple N etwork M anagement Protocol SN M P 101 snmp SNMP Reference Manual 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 atom 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 Reas
43. is infinity snmp_priority atom lt optional gt Defines the Erlang priority for all SN MP processes D efault is normal 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 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 in 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 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 ar
44. 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 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 vacm conf Simple N etwork M anagement Protocol SN M P 149 snmp_view_based_acm_mib SNMP Reference Manual add_sec2group SecModel SecName GroupName gt Ret Types e SecM odel v1 v2c usm e SecN ame string e GroupN ame string e Ret ok Key error Reason e Key term e Reason term Adds a security to group definition to the agent config Equivalent to one vacmSecurityToG roup line in the vacm conf file
45. 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 SNMP 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 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 snmpmibserver_verbosity silence info log debug trace lt optional gt Specifies the startup verbosity for the SNMP mib server Default is silence snmp_mib_storage ets dets Dir dets Dir Action mnesia Nodes mnesia Nod 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
46. lt lt lt __ gt 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 SNMP PD Us to a master agent and receives SN M P PDUsfrom the master agent The most common behaviour of a N et if process is that is receives bytes from a network decodes them into an SNMP 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 Net 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 Net if process The default N et if process is implemented in the module snmp_net_if and it uses UDP as the transport protocol This section describes how to write a Net 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 anew 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
47. now be overwritten Ok y n ONE 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 Simple N etwork M anagement Protocol SN M P 29 Chapter 1 SNMP User s Guide 2 gt application start snmp ok 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 Default value is always silence The old debugging is still available an
48. 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 Simple N etwork M anagement Protocol SN M P 65 Chapter 1 SNMP User s Guide 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 conceptual row may not be made available for use by the managed device For those columns to which
49. 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 a SN MP entity To identify the instances specified by an MIB module a method to distinguish the actual instance by its scope or context is used Often the context is a physical or alogical 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 network interface four pieces of information are needed the snmpEnginelD of the SNMP entity which provides access to the management
50. seq4449 Corrupt snmp_local_db log files cause snmp crash Changes to the local db is stored on disk ina logfile In a takeover 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 OT P 3534 Aux Id seq4437 snmp date_and_time rewritten to not rely on erlang now Own Id OTP 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 Simple N etwork M anagement Protocol SN M P 81 Chapter 1 SNMP User s Guide e Unneccessary print outs in snmp_net_if Own Id OTP 3410 Aux Id seq4241 e A crash report from disk_log was generated when the SNMP agent was started for the very first time Own Id OTP 3393 Aux Id seq4211 e The SNMP 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 28 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 e The fact that the MIBS SN M Pv2 SM RFC 1215 R
51. 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 MPEA MIB 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 SMIv1 with the TRAP TYPE macro in the definition of an MIB see RFC1215 The corresponding macro in SM Iv2 isNOTIFICATION TY PE 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 M IB 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 must be provided This parameter is used as an index in the snmpNotifyTable and the management targets defined by that single entry is used
52. table which means that the M nesia table may have columns which are use internally and are not seen by SN MP Still the data model from SNMP must be maintained Although this is undesirable it isa 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 SNMP 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 SNMP 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 orasingleterm ifN 1 Refer to the M nesia User s Guide for information on how to declare a M nesia table as an SNMP 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
53. to refer to an existing item in the index insert Index Key Value gt NewIndex Types e Index N ewlndex 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 KeyDid Types e Index index Simple N etwork M anagement Protocol SN M P 123 snmp _index SNMP Reference Manual e Key key e KeyOid NextKeyO id oid Converts Key to an OBJECT IDENTIFIER new KeyTypes Types e KeyTypes key_types Creates a new snmp index structure The key_types type is described above 124 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_local_db snmp_local_db Erlang M odule 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 dets It is possible to manually dump the database 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 Thesecond problem occurs if the database is large dumping the entire database may take some considerable time and it ma
54. 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 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 Module The snmp_supervisor is the supervisor for the SNMP 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 fok pid error already_started pid error Reason Types e Opts opt e opt priority Prio Starts a supervisor for the SNMP 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 isan Erlang priority All SNMP processes use this priority Default is the same as default in the Erlang runtime system start_master DbDir ConfDir start_master DbDir ConfDir Opts gt ok pidQ error already_started pidQ error Reason Types e DbDir string e ConfDir string e Opts opt
55. used if this object is not defined in a MIB loaded by the manager O r if you explicitly want to send a request of wrongly typed data start Options 130 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_mgr start_link Options gt void Types e Options options Starts the SN M P manager M andatary options are e agent Agent where Agent is the IP address of the agent int int int int or the name of the host string Optional options are e agent_udp int theUDP port that the agent listens to Default is 4000 e trapudp int theUDP port where the manager will receive traps Default is 5000 e community string the community string that is sent in the requests from the manager D efault is public e context string the context that is sent in v3 requests from the manager an Default is e user string the USM user name that is sent in v3 requests from the manager D efault is initial e engine_id string the engine ID of the agent Used in v3 only D efault is agentE ngine e context_engine_id string the context engine ID used in v3 requests Default is the same as engine_id e sec_level noAuthNoPriv authNoPriv authPriv the requested security level Used in v3 only Default is noAuthNoPriv e dir string the directory where the file usm conf is located This file is only needed if v3 is use
56. 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 66 Simple N etwork M anagement Protocol SN M P SYNTAX 1 12 SNMP Appendix B 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 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 the DESCRIPTION clause it is suggested that this period be approximately 5 minutes in length This
57. viewType read write notify Figure 1 4 Overview of the mechanism of M IB 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 aviewName 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 collection 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 I
58. 0 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 PD U 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 MIB 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 Valid return values e noError e badValue noSuchName genErr SN MPvl e noAccess noCreation inconsistentValue resourceUnavailable inconsistentName genErr SN MPv2 f undo NewValue ExtraArg
59. 1 2 0 ooo eo 82 1 13 205N MP Development Toolkit v3 1 0 ooo 83 1 13 30SNMP Development Toolkit v3 1 o ooo 84 Simple N etwork M anagement Protocol SN M P Vv 2 SNMP Reference M anual 2 1 POD EEEE E AA 2 2 MM iy Ger tad BP bok ie ge SE ME ew wl wee a ar ae Ae ae e 2 3 snmp_community mib aaa aaa a 2 4 SAMPER a a a A E dl dg dead isa 2 5 SNMP Eror OS er Arce ashe poe Ee oe oe fate ele tee a a Ge esl ete de ee 2 6 SHIM PEFlOPPeP Olt ti din A AAs te e ee ae ae AAA india tas Me Ne bee oe ge oo 2 7 SHIM p framew Ork MIDs 20 ese y Se Se Sete ge a ake Wes ee a amp hee 2 8 SIM P GENETI GC Fok E a SCE eee ae NS RAS AE Gee ee OT 2 9 SOMPzINdEXy ei eee BRR AA A BR ARES Do BRS 2 1051 simpo ca dD vacio ke woe ee ee Y ri ty are ee e e Mes amp a ZAL SNMP MI we ok nk diag aw era a ae O Aa aa ea GG at o 212 gt SSHIMPZM Pea A Arie te aaah aie Mavala het Ph de dot Ae Ae gh tet a 2 13 snmp_notificationmib aaa ee 2 44 a A a a ESS ee Sy O ee ee oe ah a a 2 15 simp tandard MiD s sricu re op ad od a Pe A e a de 216 SHIMP SUPEMVISOR Sata A Bar ee ate ohare we a Ae eee Pas ZAP Mp target MID cita AI A Oa toe oe AE e T 2 18 snmp_user_basedsmimib o o e 2 19 snmp_view_based_acmimib o o e List of Figures List of Tables vi Simple N etwork M anagement Protocol SN M P 85 96 98 110 112 113 114 115 117 121 125 128 133 135 137
60. 109 Assign a new verbosity for the process snmp_community_mib The following functions are exported e configure ConfDir gt void page 110 Configure the SNM P COMMUNITY MIB e reconfigure ConfDir gt void page 110 Configure the SNM P COMMUNITY MIB e add_community Idx CommName SecName CtxName TransportTag gt Ret page 111 Added one community e delete_community Key gt Ret page 111 D elete one community snmp_error The following functions are exported e config err Format Args gt void page 112 Called if a configuration error occurs e user_err Format Args gt void page 112 Called if a user related error occurs snmp error_io The following functions are exported e config err Format Args gt void page 113 Called if a configuration error occurs e user_err Format Args gt void page 113 Called if a user related error occurs 88 Simple N etwork M anagement Protocol SN M P SNMP Reference M anual snmp_error_report The following functions are exported e config err Format Args gt void page 114 Called if a configuration error occurs e user_err Format Args gt void page 114 Called if a user related error occurs snmp _framework_mib The following functions are exported e configure ConfDir gt void page 115 Configure the SN MP FRAMEWORK MIB e initQ gt voidQ page 115 Initialize the SN MP FRAMEWORK MIB e add_context C
61. 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 SNMP Reference Manual snmp_mgr Exports expect Id What gt ok error Id Reason expect Id ErrorStatus ErrorIndex Varbinds expect Id trap Enterp Generic Specific Varbinds expect Id v2trap Varbinds expect Id report Varbinds expect Id inform InformReply Varbinds Types e Id term e What any trap timeout Varbinds ErrorStatus e ErrorIndex integer e Enterp oid e Generic integer e Specific integer InformReply true false error ErrorStatus Errorlndex e 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 are pending e ErrorStatus s an atom which describes an error message See documentation for the SNMP agent e Varbinds sa list of O id Value 0 id 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 reque
62. 3 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 MIB 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 M nesia 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 SN MP 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 the ASN 1 file is completed let the MIB compiler generate a default implementation and develop the management application from this 22 Simple
63. 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 Simple N etwork M anagement Protocol SN M P 61 Chapter 1 SNMP User s Guide 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 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 ina 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 a default and making the conceptual row available for use by the managed device Interaction 1 Sel
64. 843 Aux Id Seg 5096 Incompatibilities 1 13 11 SNMP Development Toolkit v3 4 2 Version 3 4 2 supports code replacement in runtime from to version 3 4 1 and 3 4 Improvements and new features e Added new date and time function s utilizing the local_time_to_universal_time_dst of the calendar module See local_time_to_date_and_time_dst page 104 and date_and_time_to_universal_time_dst page 1011 The old functions local_time_to_date_and_time 1 and date_and_time_to_universal_time 1 has been obsoleted and will be removed at a later date Own ld OTP 4873 Simple N etwork M anagement Protocol SN M P 73 Chapter 1 SNMP User s Guide Reported Fixed Bugs and Malfunctions e Handling of subagents with subtrees not in sequence W hen a subagent has two subtrees registered A and C and another agent has a subtree between the two B A get next operation for the last variable in A would return the first variable in B which is wrong The master agent did check this but not very good Martin Bjrklund Own Id OTP 4879 Incompatibilities e Functions snmp local_time_to_date_and_time 1 and snmp date_and_time_to_universal_time 1 has been obsoleted and will be removed at a later date 1 13 12 SNMP Development Toolkit v3 4 1 Version 3 4 1 supports code replacement in runtime from to version 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent Minor errorsin debug macros and sample config file Serge
65. 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 Mapping of SN M Pv2 error message to SN M Pv1 SN M Pv2 message SN M Pv1 message wrongl ype badValue continued 58 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B continued wrongLength wrongEncoding wrongValue noC reation inconsistentV alue resourceU navailable commitFailed undoFailed notW ritable 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 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 by the managed device createAndGo which is supplied by a management stat
66. Address OBJECT TYPE SYNTAX DisplayString SIZE 0 255 ACCESS read write STATUS mandatory DESCRIPTION Address of friend friendsEntry 3 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 4 myName fIndex DESCRIPTION This trap is sent when something happens to the friend specified by flIndex a 1 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 M IBs imported by EX 1 M IB mib must be present and compiled in the current directory STANDARD MIB bin RFC 1213 MIB 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 snmp_mgr start_link agent dront ericsson se community all rights ok lt 0 89 0 gt hh a get next request with one OID 2
67. B 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 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 If there is sufficient information available then the status column is set to notInService
68. Bytes 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 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 Default 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 Otherwise no agents are started D efault is master 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 SN MP internal db files are stored Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp 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 agen
69. COMMUNITIES 0 kk tow sn e ll Pe ee aa il ee ws 47 1 8 5 MIBViewsforVACM o e e eee 48 1 8 6 Security data for USM o e 2 e 48 1 8 7 N OtiTysD GTINIEIONS o na y yo Redo e Ree ee TA ak de T 49 1 8 8 Target Address Definitions 0 0 o 49 1 8 9 Target ParametersDefinitions 1 0 o 50 Definition of Instrumentation Functions o o 50 1 9 1 Variable Instrumentation o e 50 1 9 2 Table Instrumentation 000 e o oo ee SP A ee Ge de ee 52 Definition Of Net if s voto tos ee ea ee ehh Bae BR EAS Ot ee BRA 55 1 10 1 Mandatory Functions 2 2 e oo 56 LAO Z MiCSSAGCS o a a a a ok ee Go ee ae het 56 SNMP APpENdIX A hoe oe ae A Ae sk SE Ae od 58 LTV Appendix A s 4 amp ao ye ee ye HE Ee oe ed ee ee OS YS 58 SNMP Appendix B 5 ace eo See ee ey ole Kee Pee ee a Ghee ee eS 59 TeI2 S Appendix Bes a3 Sk ADR Sie eo ee RMR EEG SS 59 SNMP Release Notes e a 68 1 13 1 SNMP Development Toolkit v3 4 12 0 ooo o 68 1 13 2 SNMP Development Toolkit v3 4 11 o o ooo 68 1 13 3 SNMP Development Toolkit v3 4 10 o ooo o 69 Simple N etwork M anagement Protocol SN M P 1 13 4 SNMP Development Toolkit v3 4 9 o eee eee 69 1 13 5 SNMP Development Toolkit v3 4 8 0 ooo ee 70 1 13 6 SNMP Development Toolkit v3 4 7 oo 70 1 13 7 SNMP D
70. CTET 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 type correlates to the key_types type If the key_types isasingle atom the corresponding key 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
71. D string Name string SecN ame string Clone zeroD otZero integer AuthP usmN oAuthProtocol uumHMACMD5AuthProtocol usmH MACSHAAuthProtocol AuthKeyC string OwnAuthKeyC string PrivP usmN oPrivProtocol usmD ESPrivProtocol PrivKeyC string OwnPrivKeyC string Public string AuthKey string PrivKey string Ret ok Key error Reason Key term Reason term Adds a USM security data user to the agent config Equivalent to one line in the usm conf file delete_user Key gt Ret 148 Types Key term Ret ok error Reason Reason term Delete aUSM security data user from the agent config 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 functions for the SNM P 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
72. DENTIFIER 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 MIB 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 M IB 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 MIB view according to the type of that entry e If 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 particular rowsin a table shall be visible SNMP COMMUNITY MIB The SNM P COMMUNITY MIB defines managed objects that is used for coexistence betwee
73. Db 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 already_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 Simple N etwork M anagement Protocol SN M P 127 snmp_mgr 128 SNMP Reference Manual snmp_mgr Erlang Module 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 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 SN MP agent The manager supports SN M Pv1 SNM 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
74. FC 1212 SNM Pv2 TC SNM Pv2 CONF and RFC 1155 SM I 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 Id 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 OTP 3350 Aux Id Reported Fixed Bugs and Malfunctions e If two Erlang nodes are started on the same host and each node starts an SN MP agent and if both agents use the same UDP 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 Debug printouts from snmp_net_if appeared even when the debug flag was not set This has been corrected Own Id OTP 3345 Aux Id seq4091 82 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes 1 13 29 SNMP Development Toolkit v3 1 1 Improvements and new features The audit trail log has been improved Now each log item also contains a time stamp Also the text format of a log produced by a call to snmp 1log_to_txt has been changed to be more line oriented The function snmp log_to_txt 4 has been added O
75. IFIER 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 Community 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 Rowlndex Value OID Value e Variable atom Simple N etwork M anagement Protocol SN M P 107 snmp SNMP Reference Manual e Column atom e OID oid e Value term e Rowlndex int Note This function is only kept for backwards compatibility reasons Use send
76. 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 Vsniseither 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 eg snmpInBadCommunityUses Extra isthe 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 Vsniseither version 1 version 2 Of version 3 Pduisan SNMP PDU record as defined in snmp_typeshrl 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 SNMP message This value is normally sent to 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 isa list of the destinatio
77. Integration aoaaa 1 4 6 Compiling from a Shell or a Makefile 00004 1 4 7 Deviations from the Standard aa aaa a ee 1 5 Running the A gent 2 Sy eke a a ea We T Pee ee EO ed 1 5 1 ConfiguringtheAgent o e e Simple N etwork M anagement Protocol SN M P OVD WOUR BR WWNNP O CO q12 1 6 1 7 1 8 1 9 1 5 2 Modifyingthe Configuration Files 0 oo 28 1 5 3 Startingthe Agent so ae sekao eee e ee ee ed EES 29 1 5 4 DebuggingtheAgent 00 30 Implementation Example oaaao e 31 KEL MBS tr ee Ree a a Ma A BAR ie TE en ee ede DE 31 1 6 2 Default Implementation o e e ee 32 1 6 3 Manual Implementation o o e 34 Advanced TOpics wets attests i Sow eae ee ee ie A oe A 39 1 7 1 When to use a Subagent aoaaa o oeeeea a 39 1 7 2 Agent Semantics r ico A le A e EEA 40 1 7 3 Subagentsand Dependencies oaoa oaa ee 41 1 7 4 Distributed Tables o e o 41 1 7 5 Fault Tolerance o e de aen A a na a A a 41 1 7 6 Using M nesia Tables as SNMP Tables aoaaa 00000002 42 1 77 Audit Trail Logging ecer eae ol o eR e ed 45 1 7 8 Deviations from the Standard 0 000 eee eee 45 Definition of Configuration Files 2 aaa aaa o 46 1 8 1 AgentInformation o o e 46 LO Zo GOMtGXtS 5 4 a AA Rd AR ae oe et A 47 1 8 3 System information o e o 47 L84
78. Simple Network Management Protocol SNMP version 3 4 Typeset in LATEX from SGML source using the DOC BUILDER 3 3 2 Document System Contents 1 SNMP User s Guide Li SSN MP Introduction caca Dita ee eee ena ae ee a Wee ae ae ae 1 1 1 Scope and Purpose y dina whee eit Ea ee ee ee es oe 11 2 Prerequisites 2444 a EE Pe ae A 1 1 3 AbOUtT HIS Manual ss ck ig veo cle ee eed ch oe ae VO Bee 1 1 4 Whereto Find More Information 00000 eee ee eens 1 2 Functional Description aaau EZE TS ioi Bre tei ea ai a a i Se ae Bee L202 FEES ok ee Ba Bea NR NN 1 2 3 SNMPv1 SNMPv2 andSNMPv3 ee ee LDA Operation e A a a dee lin AS amp Shar ted ete ag 1 2 5 SubagentsandMIBLoading 0 0 0 cee ee 1 2 6 Contexts and Communities o e e 1 2 7 Management of the Agent o e ee 12 87 Notifications m al aa bd Se a a te o Sage AS 1 3 Instrumentation Functions o e mo 1 3 1 Instrumentation Functions o 2 2 o 1 3 2 Using the ExtraArgument o o e ee 1 3 3 Default Instrumentation o o 2 0 1 34 AtOMIC SEE Aa AAA A TAS A ae VA 4 The MIB Gompiler s a araa eee sn Dd Dante a a dae td VAL Operation A ee Oe E aac a ee e ba See ee a 14 2 Importing MIBS ua woh tae ete en do e a 1 4 3 MIB Consistency Checking 2 0 e 1 4 4 vhriFileGeneration e 0 0 0 es 1 4 55 Emacs
79. T 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 OBJECT IDENTIFIER of a MIB object given the symbolic name N ote the OBJECT IDENTIFIER is given for the object not for an instance 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 is not defined in any loaded MIB 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_to_name Db 0ID 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 Db isa 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 MIB register_subagent Agent SubTree0id Subagent gt ok error Reason Simple N etwork M anagement Protocol SN M P 105 snmp SNMP Reference Manual Types e Agent pid atom e SubTreeO id oid e SubAgent pid Registers a subagent under a subtree of another agent It is easy to make mistakes when
80. TP 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 SNMP 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 amein config file target_params conf Own Id OTP 3881 Aux Id seq5113 1 13 22 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 78 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes 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 117 Own Id OTP 3816 Aux Id seq5053 e Itis now possible to store mib data in ets dets and mnesia D efault 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 undef
81. _index The following functions are exported e delete Index gt true page 122 D elete an index table delete Index Key gt NewIndex page 123 Delete an item from the index e get Index KeyDid gt ok KeyDid Value undefined page 123 Get the item with Key0id e get_last Index gt ok Key0id Value undefined page 123 Get the last item in the index structure e get_next Index Key0id gt ok NextKeyOid Value undefined page 123 Get the next item insert Index Key Value gt NewIndex page 123 Insert an item into the index e key_to_oid Index Key gt KeyQid page 123 Convert a key to an OBJECT IDENTIFIER new KeyTypes page 124 Create a new snmp index structure snmp_local_db The following functions are exported e dump gt ok error Reason page 126 Dump the database to disk e match NameDb Pattern page 126 Perform an ets match on the table e print page 126 Print the database to screen print TableName page 126 Print the database to screen print TableName Db page 126 Print the database to screen e table_create NameDb gt bool page 126 Create a table e table_create_row NameDb RowIndex Row gt boo1 page 126 Create a row in a table e table delete NameDb gt void page 127 Delete a table e table_delete_row NameDb RowIndex gt bool page 127 Delete the row in the table Simple N etwork M anagement Protocol SN M P SNMP Re
82. _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 s 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 acolumn 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 This isthe OBJECT IDENTIFIER which specifies the element OID Value where 01D 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 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
83. _user_based_sm_mib 148 delete_view_tree_fam 1 snmp_view_based_acm_mib 151 discarded_pdu 1 snmp_mpd 134 dump 0 snmp_local_db 126 enc_encrypted_scoped_pdu 1 snmp_pdus 138 enc_message 1 snmp pdus 138 enc_message_only 1 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 101 enum_to_int 3 snmp 102 expect 2 snmp_mgr 129 expect 3 snmp_mgr 129 expect 4 snmp_mgr 129 expect 6 snmp_mgr 129 g 1 snmp mgr 129 gb 3 snmp mgr 129 generate_msg 4 snmp mpd 134 generate_response_msg 4 snmp mpd 133 get 2 snmp 102 snmp _index 123 get_agent_caps 0 snmp 102 get_index_types 1 snmp generic 118 get_last 1 snmp index 123 get_next 2 snmp index 123 get_status_col 2 snmp generic 118 get_symbolic_store_db 0 snmp 102 gn 0 snmp mgr 130 gn 1 snmp mgr 130 inc 1 snmp standard mib 140 158 Simple N etwork M anagement Protocol SN M P inc 2 snmp _standard_mib 140 info 1 snmp 103 init 0 snmp_framework_mib 115 init_mpd 1 snmp_mpd 133 insert 3 snmp_index 123 int_to_enum 2 snmp 103 int_to_enum 3 snmp 103 is_consistent 1 snmp 103 key_to_oid 2 snmp_index 123 load_mibs 2 snmp 103 local_time_to_date_and_time_dst 1 snmp 104 log_to_txt 2 snmp 104 log_to_txt 3 snmp 104 log_to_txt 4
84. able 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 HKIE3 1 2 d 5 1 2 f This is illustrated in the following table Simple N etwork M anagement Protocol 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 r
85. ables 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 M Pv2 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 OTP 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 SN MPv2c RFC 1908 2089 coexistence between SN M Pv1 and SN M Pv2 RFC 2271 RFC2273 SNMP std MIBs the Mnesia U ser s Guide the Erlang 4 4 Extensions User s Guide the Reference M anual the Erlang Embedded Systems User s G uide the System Architecture Support Libraries SASL User s Guide the Installation G uide the Asn1 User s Guide Concurrent Programming in Erlang 2nd Edition 1996 Prentice H all ISBN 0 13 508301 X Simple N etwork M anagement Protocol SN M P 1 2 Functional Des
86. 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 100 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp e Requestld int 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_dst DateAndTime gt utc Types e DateA ndTime int e utc Y Mo D H M S Converts a DateAndTime list to a list of possible universal time s 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 D ebug information is printed whenever an instrumentation function
87. access accessible throw the snmp page 98 module Own Id OTP 3725 Simple N etwork M anagement Protocol SN M P 79 Chapter 1 SNMP User s Guide 1 13 24 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 simp_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 25 SNMP Development Toolkit v3 2 0 Version 3 2 0 supports code replacement in runtime from to version 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 OTP 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 OTP 3650 Aux Id seq4844 1 13 26 SNMP Development Toolkit v3 1 4 Version 3 1 4 supports cod
88. ager 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 MIBs 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 NO U 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 applications must be dynamic as well For example if we have an equipment M IB for a rack and different M IBs for boards which can
89. arnings eg about missing accessfunction was changed into info printouts which can be seen with the compiler erlc argument verbosity info See SN MP compiler options page 98 Own Id OTP 4478 Reported Fixed Bugs and Malfunctions e The agent side set and is_set_ok operations on the snmpTargetA ddrExtTable was incorrect Own Id OTP 4477 Aux Id Seq 7444 1 13 15 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 Own Id OTP 4394 Aux Id Seg 7444 1 13 16 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 Simple N etwork M anagement Protocol SN M P 75 Chapter 1 SNMP User s Guide Improvements and new features Reported Fixed Bugs and Malfunctions Improved error handling in snmp error_report module ets lookup failure Own Id OTP 4345 Aux Id Seq 7309 SN MP NotifiyType error Calls to the functions snmp_ notification mib 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 O wn Id OTP 4329 Aux Id Seg 7367 1 13 17 SNMP Development Toolkit v3 3 5 Ve
90. at 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 in a 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 station s 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 all columns in the conceptual row that it wishes to create In response for each column there are th
91. atile 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 Simple N etwork M anagement Protocol SN M P 147 snmp_user_based_sm_mib SNMP Reference Manual add_user EngineID Name SecName Clone AuthP AuthKeyC OwnAuthKeyC PrivP PrivKeyC OwnPrivKeyC Public AuthKey PrivKey gt Ret Types Enginel
92. ce 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 Simple N etwork M anagement Protocol SN M P 109 snmp_community_mib SNMP Reference Manual snmp_community_mib Erlang Module The module snmp_communitymib implements the instrumentation functions for the SNMP COMMUNITY MIB and functions for configuring the database The configuration files are described in the SNMP 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 StorageT ype 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 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 wi
93. ce or twice If called once only there is no definition that 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 supports the 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 SN MP tool isto implement a table coordinator process responsible for coordinating the processes which hold th
94. col SN M P 151 snmp_view_based_acm_mib SNMP Reference Manual 152 Simple N etwork M anagement Protocol SN M P List of Figures 1 1 MIB Compiler Principles lt o o ee EX Starting the Agent tie o ae ee E3 SAKENILCCUUPEY ii ae a a a e eX 1 4 Overview of the mechanism of MIB selection 1 5 Contents of my table aa vk eek rt e eS 1 6 GetNextfrom 3 1 l and 5 1 1 1 7 GetNext from 3 2 1 and 5 2 1 1 8 GetNext from 3 1 2 and 4 1 2 19 ThePurposeofNetif o o a aO a Simple N etwork M anagement Protocol SN M P 153 List of Figures 154 Simple N etwork M anagement Protocol SN M P List of Tables LI Error Messages sv a a at e ah heh ene Oa at tae oe ene ee ww Sha a 59 Simple N etwork M anagement Protocol SN M P 155 List of Tables 156 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_access 8 snmp_view_based_acm_mib 150 add_addr 10 snmp_target_mib 145 add_agent_caps 2 snmp 98 add_community 5 snmp_community_mib 111 add_context 1 snmp_framework_mib 115 add_notify 3 snmp_notification_mib 135 add_params 5 snmp _target_mib 145 add_sec2group 3 snmp_view_based_acm_mib 150 add_user 13 snmp_user_based_sm_mib 148 add_view_tree_fam 4 snmp_vi
95. 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 60 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B STATE A B C D status col status column status column is is status column ACTION does not exist notReady notInService is active set status noError
96. cription 1 2 Functional Description The SNMP development toolkit contains the following parts e An Extensible multi lingual SN MP agent which understands SN M Pv1 RFC 1157 SNM Pv2c RFC 1901 1905 1906 and 1907 SNM Pv3 RFC 2271 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 RFC1902 1903 and 1904 e A multi lingual SNMP 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 SNMP agent in runtime MIBs can be loaded and unloaded at any time It is also easy to change the implementation of an M IB in runtime without having to recompile the MIB The MIB implementation is clearly separated from the agent To facilitate incremental MIB implementation the tool can generate a prototype implementation for a whole MIB 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 MIB It does not hold any data merely a definition of what data can be accessed A definition of an MIB is a description of a collection of managed objects SMI TheMIB is sp
97. d The file has the same syntax as the usm conf file for the agent e mibs List of filename MIBsto be loaded in the manager D efault is no MIBs The MIBs must be compiled e receive_type pdu msg defines the format of delivered messages D efault iS pdu e quiet incoming responses are not displayed Messages 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 sa 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 e vilv2 v3 what SNMP version to use Default is v1 e recbuf integer defines the size of a U DP socket receive buffer This is important when sending large regusts to 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 Simple N etwork M anagement Protocol SN M P 131 snmp_mgr SNMP Reference Manual stop gt void Stops the SN M P manager 132 Simple N etwork M anagement Protocol SN M P
98. d produces 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 snmpmaster_agent true ok 4 gt hh Example of output from the agent when a get next request arrives SNMP NET IF 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 IF 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 M IB can be implemente
99. d 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 SMI 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 However the compiler cannot detect O id conflicts between different M IBs 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 44 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 generate 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 functio
100. d 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 4 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 INDEX fIndex friendsTable 1 FriendsEntry SEQUENCE 4 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 friendsEntry 2 f
101. database should be used for the default instrumentation Default is volatile The option i specifies the path to search for imported compiled MIB files The directories should be strings with a trailing directory delimiter Default is The option 11 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 snmp mibs will be replaced by samp 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 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 1 e if warning info log debug and trace messages shall be shown Default is silence Note 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 and the NOTIFICATION GROUP macro for correctness or not Default is true The option deprecated specifies if a deprecated definition should be kept or not If the option is false the MIB compiler will ignore all deprecated definitions Default is true The option description
102. different operations In the following RowIndex is a list of key values for the table and Column isa column number These functions are described in detail in Definition of Instrumentation Functions page 50 New Delete Operations For scalar variables variable_access new ExtraArgl variable_access delete ExtraArg1 For tables table_access new ExtraArgl table_access delete ExtraArgl 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 ExtraArgl 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 ExtraArg1 For tables table_access set RowIndex Cols ExtraArgl Cols isa list of tuples Column NewValue These functions returns noError if the assignment was successful otherwise an error code Simple N etwork M anagement Protocol SN M P 17 Chapter 1 SNMP User s Guide Is set ok Operation Asacomplement to the set operation it is possible to specify a test function This
103. e gt value oid false page 105 Convert a symbolic name to an OID oid_to_name 0ID gt value Name false page 105 Convert an OID to asymbolic name oid_to_name Db 0ID gt value Name false page 105 Convert an OID to asymbolic name register_subagent Agent SubTreeQid Subagent gt ok error Reason page 105 Register a subagent under a subtree send notification Agent Notification Receiver page 106 Send a notification send notification Agent Notification Receiver Varbinds page 106 Send a notification send notification Agent Notification Receiver NotifyName Varbinds page 106 Send a notification Simple N etwork M anagement Protocol SN M P 87 SNMP Reference Manual e send notification Agent Notification Receiver NotifyName ContextName Varbinds gt void page 106 Send a notification e send_trap Agent Trap Community page 107 Send atrap e send_trap Agent Trap Community Varbinds gt void page 107 Send atrap universal_time_to_date_and_time UTC gt DateAndTime page 108 Conversa UTC value to DateAndTime unload mibs Agent Mibs gt ok error Reason page 108 Unload M IBs from the agent unregister_subagent Agent Subagent0idOrPid gt ok ok SubAgentPid error Reason page 109 Unregister a subagent validate_date_and_time DateAndTime bool page 109 Check if a DateA ndTime value is correct verbosity Ref Verbosity gt void page
104. e TransportTag e CommunityIndex is a non empty string e CommunityName is a string e SecurityName is a string e ContextName is a 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 M P 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 E 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 Prefixisa string e SecLevel iSnoAuthNoPriv authNoPriv Or authPriv e Match is prefix Or exact e ReadView isa 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 nu11 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 mas
105. e 2 123 get 2 123 get_last 1 123 get_next 2 123 insert 3 123 key_to_oid 2 123 new 1 124 Simple N etwork M anagement Protocol SN M P snmp_local_db dump 0 126 match 2 126 print 0 126 print 1 126 print 2 126 register_notify_client 2 127 table_create 1 126 table_create_row 3 126 table_delete 1 127 table_delete_row 2 127 table_exists 1 127 table_get_row 2 127 unregister_notify_client 1 127 snmp_mgr expect 2 129 expect 3 129 expect 4 129 expect 6 129 g 1 129 gb 3 129 gn 0 130 gn 1 130 name_to_oid 1 130 oid_to_name 1 130 r o 130 s 1 130 start 1 130 start_link 1 131 stop 0 132 snmp_mpd discarded_pdu 1 134 generate_msg 4 134 generate_response_msg 4 133 init_mpd 1 133 process_packet 4 133 snmp_notification_mib add_notify 3 135 configure 1 135 delete_notify 1 136 reconfigure 1 135 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 enc_encrypted_scoped_pdu 1 138 enc_message 1 138 enc_message_only 1 138 Index of Modules and Functions 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 0 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 s
106. e 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 M IB 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 sysCFunc get lt code gt sysCFunc set lt code gt Binary file bin Representation Figure 1 2 Starting the A gent 6 Simple N etwork M anagement Protocol SN M P 1 2 Functional Description The SNMP agent system consists of one M aster A gent 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 SNMP 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 Standard MIB Network Figure 1 3 Architecture A typical operation could include the following steps 1 The Man
107. e 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 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 SNMP 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 iS keep 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
108. e replacement in runtime from to version 3 1 3 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 80 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes 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 checked This check can now be overridden with the sys config tupple snmp_trapentry_override bool Default 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 OT P 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 OT P 3353 1 13 27 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 SN M Pv3 discovery process does not work Own Id OTP 3542 Aux Id
109. e table data and they are Called table holders All table holders 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 SN MP 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
110. ecified 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 SM 1 ASN 1 ASN 1 is used 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 Operations SNMP 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 Features To implement an agent the programmer writes instrumen
111. ecting 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 62 Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix B 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 issue a management protocol retrieval operation In order to avoid unnecessary collisions between competing management stations adjacent retrievals of this object should be different Finally the management station could select a pseudo random number to use as the index In the event th
112. ed Bugs and Malfunctions agent Default instrumentation functions mis behave on some not supported tables Could enter infinit loop Own Id OTP 5084 Aux Id Seq 8807 Incompatibilities 1 13 6 SNMP Development Toolkit v3 4 7 Version 3 4 7 supports code replacement in runtime from to version 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features e Application test directory included in the source release Own Id OTP 5056 Aux Id Seq 8738 70 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions compiler The value range part of the SYNTAX Integer32 does not handle values given as hexStr or bitStr only 10 base integers Own Id OTP 5051 Aux Id Seq 8738 compiler The mib compiler cannot handle mib traps notifications with included values O BJECTS which are defined later in the M IB Own Id OTP 5052 Aux Id Seq 8738 Incompatibilities 1 13 7 SNMP Development Toolkit v3 4 6 Version 3 4 6 supports code replacement in runtime from to version 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent Incorrect v3 password causes the agent to not send a report back to the manager and counters to not be updated due to a decode crash Martin Bjrklund Own Id OTP 5041 Incompatibilities 1 13 8 SNMP Development Toolkit v3 4 5 Version 3 4 5 supports code replacement in runtime
113. element 2 Row get_next_cols Cols Row get_next_cols Col Cols Row when Col gt 4 gt endOfTable 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 flex1_server Answer gt Answer 36 Simple N etwork M anagement Protocol SN M P 1 6 Implementation Example initO gt register ex1_server self loop loop MyName Table gt receive From get_my_name gt From exi_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 exi_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
114. equest 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 This is illustrated in the following table AAA AA O endOf Table Figure 1 7 GetNext 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 41 The function should now return ELES 2 1 gt 5 1 1 ch This is illustrated in the following table Figure 1 8 GetNext 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 laste 1 a and 3 1 1 ar 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 Note Normally the functions described 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
115. est e current _net_ifdata gt value NetIfData false page 100 Retrieve the N et_if data of the current pdu e current_request_id gt value RequestId false page 100 Retrieve the request Id of the current request e date_and time gt DateAndTime page 101 Return the current date and time as an OCTET STRING e date_and_time_to_universal_time dst DateAndTime gt utc page 101 Convert a DateA ndTime value to a list of possible utc e date_and_time_to_string DateAndTime gt string page 101 Convert a DateA ndTime value to a string debug Agent Boo1 gt void page 101 Turn debugging on off e del_agent_caps SysORIndex gt void page 101 Delete an AGENT CAPABILITY definition from the agent e enum_to_int Name Enum gt value Int false page 101 Convert an enum value to an integer e enum_to_int Db Name Enum gt value Int false page 102 Convert an enum value to an integer e get Agent Vars gt Values error Reason page 102 Perform a get operation on the agent e get_agent_caps gt SysORIndex SysORID SysORDescr SysORUpTime page 102 Return all AGENT CAPABILITY definitions in the agent 86 Simple N etwork M anagement Protocol SN M P SNMP Reference M anual get_symbolic_store_db gt Db page 102 Retrieve the symbolic store database reference info Agent gt Key Value page 103 Return information about the agent int_to_enum Name In
116. evelopment Toolkit v3 4 6 0 oo 71 1 13 8 SNMP Development Toolkit v3 4 5 0 o e e 71 1 13 9 SNMP Development Toolkit v3 4 4 0 00 00 0000 ee eee 72 1 13 10SNMP Development Toolkit v3 4 3 0 000 eee eee 72 1 13 11SNMP Development Toolkit v3 4 2 0 oo o 73 1 13 12SNMP Development Toolkit v3 4 1 0 000 eee ee eee 74 1 13 13SNMP Development Toolkitv3 4 0 00 00 cee eee 74 1 13 14SNMP Development Toolkit v3 3 8 0 00 00 00 eee eee 75 1 13 15SNMP Development Toolkit v3 3 7 o oe 75 1 13 16SNMP Development Toolkit v3 3 6 0 000 eee ee eee 75 1 13 17SNMP Development Toolkit v3 3 5 0 00000 eee eee eee 76 1 13 18SNMP Development Toolkit v3 3 4 o oo eee 77 1 13 19SNMP Development Toolkit v3 3 3 0 0 00 00 eee eee eee 77 1 13 20SNMP Development Toolkit v3 3 2 o om e 77 1 13 21SNMP Development Toolkit v3 3 1 o ooo o 78 1 13 22SNMP Development Toolkit v3 3 0 0 00 00 000 eee eee 78 1 13 233NMP Development Toolkit v3 2 2 o o o 79 1 13 245N MP Development Toolkit v3 2 1 o ooo o 80 1 13 255N MP Development Toolkit v3 2 0 0 oo 80 1 13 26SNMP Development Toolkit v3 1 4 0 ooo 80 1 13 27SNMP Development Toolkit v3 1 3 0 o oo 81 1 13 285N MP Development Toolkit v3
117. ew_based_acm_mib 150 c 1 snmp 98 c 2 snmp 98 change_log_size 1 snmp 99 config 0 snmp 99 config_err 2 snmp_error 112 snmp error_io 113 snmp error_report 114 configure 1 snmp_community_mib 110 snmp _framework_mib 115 snmp notification_mib 135 snmp _standard_mib 140 snmp_target_mib 144 snmp _user_based_sm_mib 147 snmp_view_based_acm_mib 149 current_address 0 snmp 100 current_community 0 snmp 100 current_context 0 snmp 100 current_net_if_data 0 snmp 100 current_request_id 0 snmp 100 date_and_time 0 snmp 101 date_and_time_to_string 1 snmp 101 date_and_time_to_universal_time_dst 1 snmp 101 debug 2 snmp 101 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 Simple N etwork M anagement Protocol SN M P 157 Index of Modules and Functions snmp pdus 138 dec_usm_security_parameters 1 snmp_pdus 138 del_agent_caps 1 snmp 101 delete 1 snmp _index 122 delete 2 snmp _index 123 delete_access 1 snmp_view_based_acm_mib 150 delete_addr 1 snmp target_mib 145 delete_community 1 snmp_community_mib 111 delete_context 1 snmp _framework_mib 115 delete_notify 1 snmp_notification_mib 136 delete_params 1 snmp_target_mib 146 delete_sec2group 1 snmp_view_based_acm_mib 150 delete_user 1 snmp
118. f 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 atext 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 Functions 1 3 1 Instrumentation Functions The following sections describe how the instrumentation functions should be defined in Erlang for the
119. ference M anual table_exists NameDb gt bool page 127 Check if a table exists table_get_row NameDb RowIndex gt Row undefined page 127 Get a row from the table registernotify_client Client Module gt ok error Reason page 127 Register Client as notification client unregister_notify_client Client gt ok error Reason page 127 Unregister Client as notification client snmp_mgr The following functions are exported expect Id What gt ok error Id Reason page 129 Test if the manager has received a response trap inform or report expect Id ErrorStatus ErrorIndex Varbinds page 129 Test if the manager has received a response trap inform or report expect Id trap Enterp Generic Specific Varbinds page 129 Test if the manager has received a response trap inform or report expect Id v2trap Varbinds page 129 Test if the manager has received a response trap inform or report expect Id report Varbinds page 129 Test if the manager has received a response trap inform or report expect Id inform InformReply Varbinds page 129 Test if the manager has received a response trap inform or report g Oids gt void page 129 Send a get request gb NonRepeaters MaxRepetitions Dids gt void page 129 Send a get bulk request gn Oids gt void page 130 Send a get next request gn gt void page 130 Send a get next request gn N gt void
120. 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 SNMP Reference Manual snmp Addresses isa list of management target addresses If UDP over IP is used thisisa 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 R equest 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 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 notification specification e Column RowIndex Value where Column is the symbolic name of a column variable RowIndex isa 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 IDENT
121. 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 send notification Agent Notification Receiver Varbinds In this function 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 trap is the RowIndex appended to the OBJECT IDENTIFIER for the table column This isthe 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 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 for extra variables that should be sent in the notification but were not defined in the notification specification The notification is sent
122. from to version 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent snmp _user_based_sm_mib add_user 13 calls undef function snmp _conf check_user 1 Should have been snmp_conf check_usm 1 Introduced in snmp 3 4 3 Own Id OTP 5017 Simple N etwork M anagement Protocol SN M P 71 Chapter 1 SNMP User s Guide Incompatibilities 1 13 9 SNMP Development Toolkit v3 4 4 Version 3 4 4 supports code replacement in runtime from to version 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent SNMP trap send stops after change to Access Group Data Own Id OTP 4999 Aux Id Seq 8626 agent get next on vacmA ccessTable exits badarg for column 3 O wn Id OTP 5000 Aux Id Seq 8626 Incompatibilities 1 13 10 SNMP Development Toolkit v3 4 3 Version 3 4 3 supports code replacement in runtime from to version 3 4 2 3 4 1 and 3 4 Improvements and new features agent Improved load control Added a new config parameter snmp_req_limit which allow for some load control see configuration parameters page 27 Own Id OTP 4980 Aux Id Seq 8446 agent The example manager cannot handle start option receive type Nicolas N iclausse Own Id OTP 4993 compiler N otifications now included in generated header files Own Id OTP 4931 Aux Id Seq 8421 compiler Defines of the SN M Pv2 TC now builtin This also means that the SNM Pv2 TC prov
123. g which for a deployed agent should have a very 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 is a string 1 8 3 System Information The system information should be stored in a file called standard conf Each entry is a 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 isaterm CommunityIndex CommunityName SecurityName ContextNam
124. generate msg Vsn Pdu MsgData To gt ok PacketsAndAddresses discarded Reason Types e Vsn version 1 version 2 version 3 e Pdu pdu M sgD ata msg_data To dest_addrs PacketsA ndA ddresses T Domain TAddress Packet TDomain snmpU D PD omain TA ddress Ip U dp Ip integer integer integer integer 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 SNMP message This value is received in asend_pdu or send_pdu_req message from the agent In SNM Pv1 and SNM Pv2c 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 134 Types e Variable atom Increments the variable associated with a discarded pdu This function can be used when the net_if process receives a discarded_pdu message from the agent Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp _notification_mib snmp_notification_mib Erlang M odule The module snmp_notificationmib implements the instrumentation functions for the SN M P NOTIFICATION M IB and functions for configuring the database The configuration files are described in the SN MP User s M anual
125. gers and the agent If the snmp application is configured as a 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 Mnesia DBMS can be used for storing data of SNMP 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 W hen 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 SNMP 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 SN MP
126. get next and get bulk For example snmp_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 Management 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 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
127. given in the snmp_config_dir configuration parameter These files are read at start up and are used to initialize the SN M Pv2 M IB or STANDARD M IB SNM P FRAMEWORK MIB SNM P M PD MIB SNM P VIEW BASED ACM MIB SNMP COMMUNITY MIB SNM P USER BASED SM M IB SNM P TA RG ET M IB and SNMP NOTIFICATION MIB refer to the M anagement of the A gent page 9 for a description of the M IBS 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 atuple 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 snmpEngineID is a strin
128. 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 D efault 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 M IBs 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 i 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 snmp c MY MIB il snmp priv mibs myapp priv mibs finds the lastest version of the snmp and myapp applications in the OTP system an
129. he 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 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 O 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 MibN ame 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 MibN ame e MibN ame 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 Simple N etwork M anagement Protocol SN M P 103 snmp SNMP Reference Manual Dir code priv_dir my_app mibs snmp load_mibs snmp_master_agent Dir MY MIB local_time_to_date_and_time_dst Local gt DateAndTime Types e Local Y Mo D H M S
130. he 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 necessary when in fact Simple N etwork M anagement Protocol SN M P 1 12 SNMP Appendix
131. his function must be called from within a transaction mnesia transaction 1 Or mesia dirty 1 variable_func Op1 NameDb variable func 0p2 Val NameDb gt Ret Types e Op1 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 a zero value depending on the type The delete function does not delete the variable from the database The function 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 Simple N etwork M anagement Protocol SN M P 119 snmp _generic 120 SNMP Reference M anual 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 table_func new NameDb myTable func delete NameDb gt pass unchanged snmp_generic tablefunc delete NameDb hh change row myTable_func is_set_ok RowIndex Col
132. ich 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 M IBs 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 MIBs 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 SNM Pv1 to SNM Pv2 MIBs and implementations for both of these versions are Provided in the distribution The M IB file for SN M Pv1 is called Simple N etwork M anagement Protocol SN M P 9 Chapter 1 SNMP User s Guide STAN DARD 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 STAN DARD M IB 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 objects in these two MIBs An SNM Pv3 agent must implement the SN MP FRAMEWORK MIB and SNM P M PD M IB These M IBs are loaded b
133. ided with this application is the proper one Own Id OTP 4934 Aux Id Seq 8419 agent A dded functions to add delete config in runtime equivalent to the config files add_community 5 page 110 and delete_community 1 page 111 add_context 1 page 115 and delete_context 1 page 115 72 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes add_notify 3 page 135 and delete_notify 1 page 136 add_addr 10 page 145 delete_addr 1 page 145 add_params 5 page 145 and delete_params 1 page 146 add_user 13 page 147 and delete_user 1 page 148 add_sec2group 3 page 149 delete_sec2group 1 page 150 add_access 8 page 150 delete access 1 page 150 add_view_tree fam 4 page 150 and delete_view_tree_fam 1 page 151 Own Id OTP 4996 Reported Fixed Bugs and Malfunctions agent Access with typo causes system crash Adding a rudimentary type check to the set and is_set_ok access functions SNMP COMMUNITY MIB snmpCommunityTable 3 SNMP NOTIFICATION MIB snmpNotifyTable 3 SNMP TARGET MIB snmpTargetAddrTable 3 snmpTargetParamsTable 3 SN M P U SER BA SED SM M IB usmUserTable 3 SNM P V IEW BASED ACM M IB vacmSecurityToGroupTable 3 vacmAccessTable 3 amp vacmViewTreeFamilyTable 3 Own Id OTP 4978 Aux Id Seq 8380 compiler SNMP compiler cannot handle M IBs without object defs Luke Gorrie Own Id OTP 4981 agent Instrumentation function usmU serTable exited on bad values Own Id OTP 3
134. ification_mib SNMP Reference Manual Types e Name string e Tag string e Type trap inform e Ret ok Key error Reason e Key term e Reason term Adds a notify definition to the agent config Equivalent to one line in the notify conf file delete _notify Key gt Ret Types e Key term e Ret ok error Reason e Reason term D elete a notify definition from the agent config 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 PDUs 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 snmpv3 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 hrl Encoding and decoding must be done explicitly when writing your own Net if process Exports dec_message byte gt Message Types e Message message Decodes a list of bytes into an SNM P Message N ote if there is a v3 message the msgSecurityParameters are not decoded They must be explicitly decoded by a call to
135. ime_dst 1 101 debug 2 101 del_agent_caps 1 101 enum_to_int 2 101 enum_to_int 3 102 get 2 102 get_agent_caps 0 102 get_symbolic_store_db 0 102 info 1 103 int_to_enum 2 103 int_to_enum 3 103 is_consistent 1 103 load_mibs 2 103 local_time_to_date_and_time_dst 1 104 log_to_txt 2 104 log_to_txt 3 104 log_to_txt 4 104 log_to_txt 5 104 log_to_txt 6 104 log_to_txt 7 104 mib_to_hr1 1i 105 name_to_oid 1 105 name_to_oid 2 105 oid_to_name 1 105 oid_to_name 2 105 register_subagent 3 105 send_notification 3 106 send_notification 4 106 send_notification 5 106 send_notification 6 106 send_trap 3 107 send_trap 4 107 universal_time_to_date_and_time 1 108 unload_mibs 2 108 unregister_subagent 2 109 validate_date_and_time 1 109 verbosity 2 109 snmp_community_mib add_community 5 111 configure 1 110 delete_community 1 111 reconfigure 1 110 snmp error config_err 2 112 user_err 2 112 snmp error_io config_err 2 113 user_err 2 113 snmp_error_report config_err 2 114 user_err 2 114 snmp_framework_mib add_context i 115 configure 1 115 delete_context 1 115 init o 115 snmp _generic get_index_types 1 118 get_status_col 2 118 table_func 2 118 table_func 4 118 table_get_elements 3 119 table_next 2 119 table_row_exists 2 119 table_set_elements 3 119 variable_func 2 119 variable_func 3 119 variable_get 1 119 variable_set 2 119 snmp _index delete 1 122 delet
136. ined SN MP log conversion function Own Id OT P 3733 Snmp manager get bulk request failure This is actually a U D P problem OT P 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 aget bulk request could easily exceed 1024 bytes resulting in an erroneous message The size of recbuf for the snmp manager app is now configurable recbuf integer see manager options page 131 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 23 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 Improvements and new features e Itis now 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
137. information at device X the contextName device X the managed object type ifDescr and the instance 1 In SNM Pv1 and SN MPv2c 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 SNMP 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 appropriate configuration file Configuration Files page 27 1 2 7 Management of the Agent There is a set of standard M IBs wh
138. ins 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 Default 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 o
139. ion 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 Simple N etwork M anagement Protocol SN M P 59 Chapter 1 SNMP User s Guide 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 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 This textual convention may be used for a MIB table irrespective of whether the values of that table s
140. ivalent to one line in the target_addr conf file delete_addr Key gt Ret Types Delete a target address definition from the agent config add_params Name MPModel SecModel SecName SecLevel gt Ret Key term Ret ok error Reason Reason term Types Name string MPM odel v1 v2c v3 SecM odel v1 v2c usm SecN ame string SecLevel noA uthN oPriv authN oPriv authPriv Ret ok Key error Reason Key term Reason term Simple N etwork M anagement Protocol SN M P 145 snmp_target_mib SNMP Reference Manual Adds a target parameter definition to the agent config Equivalent to one line in the target_params conf file delete_params Key gt Ret Types e Key term e Ret ok error Reason e Reason term Delete a target parameter definition from the agent config 146 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_user_based_sm_mib snmp_user_based_sm_mib Erlang M odule The module snmp_user_based_sm_mib implements the instrumentation functions for the SN MP USER BASED SM M IB and functions for configuring the database The configuration files are described in the SNMP 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 vol
141. k with all ones 1 8 6 Security data for USM 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 U SER BA SED SM M IB Each entry is a term EngineID UserName SecName Clone AuthP AuthKeyC OwnAuthKeyC PrivP PrivKeyC OwnPrivKeyC Public AuthKey PrivKey a e EnginelDisa string e UserName isa string e SecName is a string e Clone iS zeroDotZero or alist of integers e AuthP is either 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 is a 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 User 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 Notify Definitions The information about Notify Definitions should be stored in a file called notify conf The corresponding table is snmpNotifyTab
142. l iSnoAuthNoPriv authNoPriv Or authPriv 1 9 Definition of Instrumentation Functions The section D efinition 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 SNM 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 SNM 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 M IB 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 function 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 5
143. 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 D ateA ndTime list The unversal time value on the same format as defined in calendar 3 unload mibs Agent Mibs gt ok error Reason 108 Types e Agent pid atom e Mibs MibN ame Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp e MibN ame string Unloads M IBs into an agent If it cannot unload all M IBs it will indicate where unloading was aborted unregister_subagent Agent SubagentOidOrPid 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 from all trees in Agent validate_date_and_time DateAndTime bool Types e DateAndTime term Checks if DateAndTime is a correct DateAndTime value as specified in RFC 1903 This function can be used in instrumentation functions to validate a D ateAndTime 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 tra
144. le N etwork M anagement Protocol SN M P 83 Chapter 1 SNMP User s Guide 1 13 30 SNMP Development Toolkit v3 1 Improvement and new features e Adaption to new format of exit codes 84 Simple N etwork M anagement Protocol SN M P SNMP Reference M anual Short Summaries Application snmp page 96 The SNMP Application Erlang M odule snmp page 98 Interface Functions to the SN MP toolkit Erlang M odule snmp_community_mib page 110 Instrumentation Functions for SNM P COMMUNITY MIB Erlang M odule snmp error page 112 Functions for Reporting SN MP Errors through the error_logger Erlang M odule snmp error_io page 113 Functions for Reporting SN MP Errors on stdio Erlang M odule snmp error_report page 114 Functions for Reporting SN MP Errors Erlang M odule snmp_framework_mib page 115 Instrumentation Functions for SN M P FRAMEWORK MIB Erlang M odule snmp _generic page 117 Generic Functions for Implementing SN MP Objects in a Database Erlang M odule snmp_index page 121 Abstract D ata Type for SN MP Indexing Erlang M odule snmp_local_db page 125 The SNMP built in database Erlang M odule snmp_mgr page 128 SNM P M anager Erlang M odule snmp_mpd page 133 M essage Processing and Dispatch module for SNMP Erlang M odule snmp_notification_mib page 135 Instrumentation Functions for SNM P NOTIFICATION MIB Erlang M odule snmp_pdus page 137 Encode and D ecode Functions for SN MP PDUs
145. le in the SNM P NOTIFICATION MIB Each entry is a term NotifyName Tag Type e NotifyName is a unique non empty string e Tag isa string e Type iStrap Or inform 1 8 8 Target Address Definitions The information about Target Address Definitions 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 Engineld TMask MaxMessageSize TargetName is a unique non empty string Ip is alist of four integers Udp is an integer Timeout is an integer RetryCount is an integer TagList is a string ParamsName is a string Engineldisa 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 9 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 TA RG ET M IB Each entry is aterm ParamsName MPModel SecurityModel SecurityName SecurityLevel e ParamsName is a unique non empty string e MPModel iS vi v2c or v3 e SecurityModel iSvi v2c Or usm e SecurityName is a string e SecurityLeve
146. ll 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 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 community conf 110 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp_community_mib add_community Idx CommName SecName CtxName TransportTag gt Ret Types e Idx string e CommN ame string e SecN ame string e CtxName string e TransportTag string e Ret ok Key error Reason e Key term e Reason term Adds a community to the agent config Equivalent to one line in the community conf file delete_community Key gt Ret Types e Key term e Ret ok error Reason e Reason term Delete a community from the agent config Simple N etwork M anagement Protocol SN M P 111 snmp _error SNMP Reference M anual snmp_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
147. lowing functions are exported e configure ConfDir gt void page 140 Configure the STAN DARD M IB 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 SNM Pv2 M IB reinit Q gt void page 141 Reset all snmp counters to O 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 ok pidQ error already_started pid error 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 93 SNMP Reference M anual 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
148. mat 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 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp framework_mib snmp_framework_mib Erlang M odule The module snmp framework_mib implements instrumentation functions for the SNM P FRAMEWORK MIB and functions for initializing and configuring the database The configuration files are described in the SNMP 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 SNM P 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
149. n SNM Pv1 and SNM Pv2c 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 M P USER BA SED SM M IB defines managed objects that is used for the U ser 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 from the configuration files these rows will automatically have storage type nonVolatile Should the agent restart all nonVolatile rows
150. n 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_types hrl 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 SNM Pv1 and SNM Pv2c 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 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 SNMP group in MIB II It can use the functions in the module snmp_mpd for this purpose refer to the Reference M anual section snmp 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
151. n 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 S 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 SNMP 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 entryObject 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 SMIv2 hyphens are allowed for objects converted from SM Iv1 but not for others This is impossible to check for the compiler If a word is a keyword in any of SMIv1 or SM Iv2 it is a keyword in the compiler deviates from SM lv1 o
152. n 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 specify that the IP and port address should be reusable If false the agent the address is set to reusable D efault 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_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 Simple N etwork M anagement Protocol SN M P 27 Chapter 1 SNMP User s Guide snmp multi_threaded bool lt optional gt If true the agent is multi threaded with one thread for each get request D efault is false snmp_req_limit integer infinity lt optional gt The number of simultaneous requests get get next and get bulk the agent will allow Default
153. nly 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 M IBs 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 IBs use this A definition has normally a status field When the status field has the value deprecated then the MIB compiler will ignore this definition With the MIB compiler option deprecated true the M 1B 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 the configuration files e starting the agent e debugging the agent Refer also to the chapter Definition of Configuration Files page 46 which conta
154. nmp_target_mib add_addr 10 145 add_params 5 145 configure 1 144 delete_addr 1 145 delete_params 1 146 reconfigure 1 144 set_target_engine_id 2 145 snmp_user_based_sm_mib add_user 13 148 configure 1 147 delete_user 1 148 reconfigure 1 147 snmp_view_based_acm_mib add_access 8 150 add_sec2group 3 150 add_view_tree_fam 4 150 configure 1 149 delete_access 1 150 delete_sec2group 1 150 delete_view_tree_fam 1i 151 reconfigure 1 149 start 1 snmp_mgr 130 start_link 1 snmp_mgr 131 start_master 2 snmp _supervisor 142 start_master 3 snmp _supervisor 142 start_sub 0 Simple N etwork M anagement Protocol SN M P 161 Index of Modules and Functions snmp _supervisor 142 start_sub 1 snmp _supervisor 142 start_subagent 3 snmp _supervisor 143 stop 0 snmp_mgr 132 stop_subagent 1 snmp _supervisor 143 sys_up_time 0 snmp _standard_mib 141 table_create 1 snmp_local_db 126 table_create_row 3 snmp_local_db 126 table_delete 1 snmp_local_db 127 table_delete_row 2 snmp _local_db 127 table_exists 1 snmp_local_db 127 table_func 2 snmp generic 118 table_func 4 snmp generic 118 table_get_elements 3 snmp generic 119 table_get_row 2 snmp_local_db 127 table_next 2 snmp generic 119 table_row_exists 2 snmp generic 119 table_set_elements 3 snmp generic 119 universal_time_to_date_and_time 1 snmp 108 unload_mibs 2 snmp 108 un
155. o 4 define createAndWait 5 emp_table set RowIndex 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 empTable 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 ok createAndGo gt true ok 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 a read_write_log In awrite_log all set requests and their responses are stored No get requests or traps are stored in awrite_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 CPU load needed for the log mechanism This means that the log is not h
156. o 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 Net 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 R equest 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 OF version 3 Pdu is the 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 N et if process from a master agent as a response to a previously received request Vsniseither version 1 version 2 Of version 3 Pduisan SNMP PDU record as defined in snmp_typeshrl with the SN MP response Type isthe pdu type 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 To is the destination address
157. on fatom 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 RU pTime 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 102 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 N etwork M anagement Protocol SN M P SNMP Reference Manual snmp info Agent gt Key Value Types e Agent pid atom Returns a list a dictionary containing information about the agent Information includes loaded MIBs 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 T
158. or 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 lt n 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 Oid Pid Common data types The following data types are used in the functions below e index e 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 121 snmp_index SNMP Reference Manual 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 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 O
159. 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 SN M 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 SN MPv2 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 SM 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 SNMP agent MIB in ASN sysContact OBJ ECT TYPE Associaton Me SYNTAX DisplayString 4sysContact mymod sysCFunc MIB Compiler Binary Representation Figure 1 1 MIB Compiler Principles The compiler parses the SM fil
160. 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 made to generic_access get IPADR Yet another possibility closer to the hardware could be ipAdr my_module generic_access 16 254
161. p definition 94 Simple N etwork M anagement Protocol SN M P SNMP Reference M anual e add_access GroupName Prefix SecModel SecLevel Match RV WV NV gt Ret page 150 Add one access definition e delete_access Key gt Ret page 150 Delete one access definition e add_view_tree_fam ViewIndex SubTree Status Mask gt Ret page 150 Add one view tree family definition e delete_view_tree_fam Key gt Ret page 151 Delete one view tree family definition Simple N etwork M anagement Protocol SN M P 95 snmp 96 SNMP Reference Manual snmp Application This chapter describes the snmp application in OTP The SNMP application provides the following services e a multilingual extensible SN MP agent e aMIB compiler e asimple manager Configuration The following configuration parameters are defined for the SNMP application Refer to application 3 for more information about configuration parameters audit_traillog false write_log readwrite_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 Default 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 Max
162. ple N etwork M anagement Protocol SN M P 67 Chapter 1 SNMP User s Guide notInService 2 the following value is a state this value may be read but not written notReady 3 the following three values are actions these values may be written but are never read createAndGo 4 createAndWait 5 destroy 6 1 13 SNMP Release Notes 1 13 1 SNMP Development Toolkit v3 4 12 Version 3 4 12 supports code replacement in runtime from to version 3 4 11 3 4 10 3 4 9 3 4 8 3 4 7 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features Reported Fixed Bugs and Malfunctions agent The SNMP agent internal data base local db uses dets and does not properly handle error s from eg lookup Own Id OTP 6210 Aux Id Seq 10404 Aux Id OT P 5838 Incompatibilities 1 13 2 SNMP Development Toolkit v3 4 11 Version 3 4 11 supports code replacement in runtime from to version 3 4 10 3 4 9 3 4 8 3 4 7 3 4 6 3 4 5 3 4 4 3 4 3 3 4 2 3 4 1 and 3 4 Improvements and new features 68 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes Reported Fixed Bugs and Malfunctions agent Error replies was composed with invalid OIDs for the following error counter usmStatsU nsupportedSecL evels point 5 O wn Id OTP 5486 Aux Id Seq 9791 Aux Id OTP 5464 Incompatibilities 1 13 3 SNMP Development Toolkit v3 4 10 Version 3 4 10 supports code replacement in runtime
163. re 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 rowsin 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 SNMP 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 Chapter 1 SNMP User s Guide SNMP VIEW BASED ACM MIB The SNM P V IEW BASED ACM MIB defines managed objects to control access to the
164. reasing 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 0 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 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 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 A _ lt lt lt
165. reconfigure ConfDir gt void page 135 Configure the SN MP NOTIFICATION MIB e add notify Name Tag Type gt Ret page 135 Added one notify definition e delete notify Key gt Ret page 136 Delete one notify definition snmp_pdus The following functions are exported e dec_message byte gt Message page 137 Decode an SN MP M essage e dec_message_only byte gt Message page 137 Decode an SNMP Message 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 138 Encode an encrypted SN MP scopedPD U 92 Simple N etwork M anagement Protocol SN M P SNMP Reference M anual e enc_message Message gt byte page 138 Encode an SN MP Message e enc _message_only Message gt byte page 138 Encode an SN MP Message but not the data part enc_pdu Pd gt byte page 138 Encode an SNMP Pdu e enc_scoped_pdu ScopedPdu gt byte page 138 Encode an SN MP scopedPD U e enc_usm_security_parameters UsmSecParams gt byte page 139 Encode SN MP UsmSecurityParameters snmp_standard_mib The fol
166. ree 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 Simple N etwork M anagement Protocol SN M P 63 Chapter 1 SNMP User s Guide 64 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 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 sufficient information to make the conceptual row available for use by the managed device T
167. register_notify_client 1 snmp _local_db 127 unregister_subagent 2 snmp 109 user_err 2 snmp error 112 snmp error_io 113 snmp error_report 114 validate_date_and_time 1 snmp 109 variable_func 2 snmp generic 119 variable_func 3 snmp generic 119 variable_get 1 snmp generic 119 variable_set 2 snmp generic 119 verbosity 2 snmp 109 162 Simple N etwork M anagement Protocol SN M P
168. 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 106 void Types Agent pid atom Notification atom Receiver no _receiver Tag Recv Tag term Recv pid atom M F A N otifyN ame string ContextN ame string Varbinds Varbind Varbind Variable Value Column RowIndex Value OID Value Variable atom Column atom OID oid Value term Row Index 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 R equests should be sent The agent sends Inform Requests and waits
169. 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 fora 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 the following two values are states these values may be read or written active 1 Sim
170. rom SNM Pv1 through SN M Pv2 to SN M 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 SN M Pv2 compared to SN M Pv1 are e The get bulx operation for transferring large amounts of data e Enhanced error codes e A more precise language for M IB 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 SN M Pv2c which uses the same message format and framework as SN M Pv1 Other experimental frameworks as exist e g SNM Pv2u and SN M Pv2 The SN M Pv3 specifications take a modular approach to SN MP 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 module which takes care of encryption and authen
171. rsion 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 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 OTP 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 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 131 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 130 and name_to_oid page 130 Own Id OTP 4250 Aux Id Seq 7270 Reported Fixed Bugs and Malfunctions e Handling of large erroneous SN M P mes
172. s 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 M IB 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 SNM Pv1 e undoFailed genErr SN MPv2 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 MPv2 1 9 2 Table Instrumentation For tables a f Operation function should be defined the function shown is exemplified with f The Operation can be new delete get next is_set_ok undo Or 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
173. s 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 Cols NameDb The funcs file would look like myTable myModule myTable_func myTable mnesia Simple N etwork M anagement Protocol SN M P SNMP Reference Manual snmp index 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 SN MP 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 F
174. s for a row The RowIndex is the list representation list of integers which follow the Cols integer in the O BJ ECT 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 O BJECT 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 set 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
175. sages corrected Encoding of the reply to these messages 76 failed due to a bug in the length encoding Also corrected counter increments Own Id OTP 4278 Aux Id Seq 7309 Simple N etwork M anagement Protocol SN M P 1 13 SNMP Release Notes 1 13 18 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 OT P 4206 Aux Id Seq 7207 e SNMP date diff check changed according to RFC 2579 was according to RFC 1903 Own Id OT P 4209 Aux Id Seg 7185 1 13 19 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 OT P 4076 e Error according to section 3 2 7a of RFC 2274 2574 reported with the wrong OID usmStatsN otlnTimeW indows instead of usmStatsN otlnTimeW indows 0 Own Id OT P 4090 1 13 20 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 e
176. se 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 ndWait 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 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 1 4 1 Operation The MIB must be written as a text file in SM Iv1 or SMIv2 using 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
177. size check M essages are truncated after 1024 chars It is provided as an example This module is the default error report module but can be explicitly configured see snmp error_report page 114 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 112 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 M odule The module snmp_error_io 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 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 114 and configuration parameters page 27 Exports config_err Format Args gt void Types e Format string e Args list The
178. snmp 104 log_to_txt 5 snmp 104 log_to_txt 6 snmp 104 log_to_txt 7 snmp 104 match 2 snmp_local_db 126 mib_to_hrl1 1 snmp 105 name_to_oid 1 snmp 105 snmp_mgr 130 Index of Modules and Functions name_to_oid 2 snmp 105 new 1 snmp _index 124 oid_to_name 1 snmp 105 snmp_mgr 130 oid_to_name 2 snmp 105 print 0 snmp_local_db 126 print 1 snmp_local_db 126 print 2 snmp_local_db 126 process_packet 4 snmp_mpd 133 r o snmp mgr 130 reconfigure 1 snmp_community_mib 110 snmp notification_mib 135 snmp _standard_mib 140 snmp_target_mib 144 snmp _user_based_sm_mib 147 snmp_view_based_acm_mib 149 register_notify_client 2 snmp_local_db 127 register_subagent 3 snmp 105 reinit 0 snmp _standard_mib 141 s 1 snmp_mgr 130 send_notification 3 snmp 106 send_notification 4 snmp 106 send_notification 5 snmp 106 send_notification 6 snmp 106 Simple N etwork M anagement Protocol SN M P 159 Index of Modules and Functions send_trap 3 snmp 107 send_trap 4 snmp 107 set_target_engine_id 2 snmp target_mib 145 snmp add_agent_caps 2 98 c 1 98 c 2 98 change_log_size 1 99 config 0 99 current_address 0 100 current_community 0 100 current_context 0 100 current_net_if_data 0 100 current_request_id 0 100 date_and_time 0 101 date_and_time_to_string 1 101 date_and_time_to_universal_t
179. 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 SNMP 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 erlc 1 for details change_log_size NewSize gt ok error Reason Types e NewSize M axBytes M axFiles e MaxBytes integer e MaxFiles integer 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 error Reason Simple N etwork M anagement Protocol SN M P 99 snmp SNMP Reference Manual 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
180. ss 1 gt mibs EX1 MIB STANDARD MIB ok lt 0 100 0 gt 2 gt imperia GH lay Name Ole ORAR 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 snmpmaster_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 A dvanced Topics describes the more advanced features of the SN MP 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
181. st 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 Dids gt void Types e Oids oid Sends a get request gb NonRepeaters MaxRepetitions Dids gt void 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 129 snmp_mgr SNMP Reference Manual 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 Thisis a nice feature for manually traversing a MIB 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 a oid to it s aliasname name_to_oid Name gt ok Oid error Reason Types e Name atom e Oid oid Transform a aliasname to it s oid s Varbinds gt void Types e Varbinds varbind 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 sl oli String Oid Integer This syntax is
182. t gt value Enum false page 103 Convert an integer to an enum value int_to_enum Db Name Int gt value Enum false page 103 Convert an integer to an enum value is_consistent Mibs gt ok error Reason page 103 Check for OID conflicts between MIBs loadmibs Agent Mibs gt ok error Reason page 103 Load M IBs into the agent local_time_to_date_and_time_dst Local gt DateAndTime page 104 Convert aLocal time value to a list of possible D ateA ndTime s log_to_txt LogDir Mibs page 104 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile gt ok ferror Reason page 104 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName gt ok ferror Reason page 104 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName LogFile gt ok ferror Reason page 104 Convert an Audit Trail Log to text format log_ to_txt LogDir Mibs OutFile LogName LogFile Start gt ok error Reason page 104 Convert an Audit Trail Log to text format log_to_txt LogDir Mibs OutFile LogName LogFile Start Stop gt ok error Reason page 104 Convert an Audit Trail Log to text format mib_to_hrl MibName gt ok error Reason page 105 Generate constants for the objects in the MIB name_to_oid Name gt value oid false page 105 Convert a symbolic name to an OID name_to_oid Db Nam
183. t These M IBs are loaded from snmp _config_dir snmp multi_threaded bool lt optional gt If true the agent is multi threaded with one thread for each get request D efault is false snmp_priority atom lt optional gt Defines the Erlang priority for all SNMP processes Default is normal 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 If false and some errors occur a new 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 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
184. tation 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 M IBs in 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 a simple and extensible model for transaction handling and consistency checking of set requests support of the subagent concept via distributed Erlang e a mechanism for sending notifications traps and informs support for implementing SN MP tables in the M nesia D BMS 1 2 3 gt 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 2570 2575 Over time as the Framework has evolved f
185. th a call to enc_message_only 1 This function should be used whenever the ScopedPDU is encrypted enc_message Message gt byte Types e Message message Encodes a message record to a list of bytes enc message_only Message gt byte Types e Message message Message is a record 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 isan encoded and possibly encrypted scopedPDU enc_pdu Pd gt byteO Types e Pdu pdu Encodes an SNMP Pdu into alist 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 M odule The module snmp_standard_mib implements the instrumentation functions for the STANDARD MIB and SNM Pv2 MIB and functions for configuring the
186. 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 with an error of inconsistentValue NOTE WELL A conceptual row having a status column with
187. 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 M P TARGET 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 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 files read are target_addr conf and target_params conf 144 Simple N etwork M anagement Protocol SN M P SNMP Reference Manual set_target_engine_id TargetAddrName Engineld 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 snmp _target_mib add_addr Name Ip Port Timeout Retry TagList Params EngineId TMask MMS gt Ret Types N ame string Ip integer length 4 Port integer Timeout integer Retry integer TagList string ParamsN ame string Engineld string TMask string length 0 or 6 MMS integer Ret ok Key error Reason Key term Reason term Adds a target address definition to the agent config Equ
188. the managed objects for the managers The View Based Access Control M odule VACM can be used with any SNMP 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 isa 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 MIB view gt securityModel __ who groupName _____ L securityName where contexrName ViewName _ securityModel who Lo securityLevel why gt
189. the network e return values from the user defined instrumentation 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 W hen 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 SNMP mana
190. this Either edit 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 28 Simple N etwork M anagement Protocol SN M P 1 5 Running the Agent ok 2 gt snmp config 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 2 1 2 3 243 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
191. tication that cannot be used with SN M Pv1 or SNM Pv2c 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 IBs 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 M Pv2c 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 avl 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 MIBs 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 M Pv1 error codes by the agent if necessary N
192. to all management targets found in the tables H owever make sure that each manager has access to the variables in the notification If a variable is outside a manager s MIB view this manager will not receive the notification N ote By definition it is not possible to send objects with ACCESS not accessible in notifications H owever 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 M aster A gent 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 referred to in the notification specification must be implemented by the agent that has the MIB loaded or by some parent to this agent I
193. tx gt Ret page 115 Added one context e delete_context Key gt Ret page 115 Delete one context snmp_generic The following functions are exported e get_status_col Name Cols page 118 Get the value of the status column from Cols e get_status_col NameDb Cols gt ok StatusVal false page 118 Get the value of the status column from Cols e get_index_types Name page 118 Get the index types of Name e table_func Opi NameDb page 118 Default instrumentation function for tables e table_func 0p2 RowIndex Cols NameDb gt Ret page 118 Default instrumentation function for tables e table_get_elements NameDb RowIndex Cols gt Values page 119 Get elements in a table row e table_next NameDb Rest0id gt RowIndex endOfTable page 119 Find the next row in the table e table_row_exists NameDb RowIndex gt bool page 119 Check if a row in a table exists e table_set_elements NameDb RowIndex Cols gt bool page 119 Set elements in a table row variable_func Op1 NameDb page 119 Default instrumentation function for tables variable func 0p2 Val NameDb gt Ret page 119 Default instrumentation function for tables Simple N etwork M anagement Protocol SN M P 89 90 SNMP Reference M anual e variable_get NameDb gt value Value undefined page 119 Get the value of a variable e variable_set NameDb NewVal gt true false page 119 Set a value for a variable snmp
194. ty Otherwise row is modified check that row exists MAA A A O friends_table is_set_ok RowIndex Cols gt RowExists case get_row RowIndex of lok _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 0 true _ gt inconsistentValue status_col false when RowExists true gt noError 0 gt Col _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 A A po as a a oa 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 Den aN EREN OCTARE get_next_cols Col Cols Row when Col lt 2 gt 2 element 1 Row
195. ucted in another package a special subagent should be used 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 a time 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 on
196. uman readable but needs to be formatted off line before 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
197. wn 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 1log_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 ld 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 OT P 3293 Aux ld Reported Fixed Bugs and Malfunctions 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 ld SN MP was not backward compatible with instrumentation functions that returned noValue unSpecified the SN MP agent crashed This has been changed by silently transforming such a return value to noValue noSuchInstance Own Id OTP 3303 Aux Id seq3975 The header file snmp_vacm hr1 was missing in the SNMP src directory Own Id OTP 3327 Aux ld Incompatibilities with v3 1 Applications that parses the audit trail log text files have to be rewritten Simp
198. x intQ 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 Name 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 a table 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 Op1 NameDb table_func Op2 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 The new function creates the table if it does not exist but only if the database is the SNMP internal db 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 arow which is to be modified or deleted
199. xception of what s mentioned in the version 3 3 0 note Improvements and new features Reported Fixed Bugs and Malfunctions e snmp _net_if subtr 2 don t handle megaseconds Own Id OTP 3920 Aux Id Seq 5174 e The mib compiler does not detect if an notification and an ordinary mib entry OBJECT IDENTITY hasthe same OID Own Id OT P 3986 Aux Id Seg 5256 Simple N etwork M anagement Protocol SN M P 77 Chapter 1 SNMP User s Guide 1 13 21 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 note Improvements and new features The UDP based N etwork Interface included in this application snmp_net_if now sets the UD P 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 Could 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 O
200. xport 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 7 Action written not read define createAndWait 5 Action written not read define destroy 6 Action written not read start gt spawn ex1 init hoses as ce eS so ea Se a Instrumentation function for variable myName hh 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 5 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 ar ee 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 end MAA A A O a If RowStatus is set then hh If set to destroy check that row does exist VA If set to createAndGo check that row does not exist AND hh that all columns are given values VA Otherwise error for simplici
201. y 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 i e receivers of notifications traps and informs These M IBs can be used with any SN MP version e SNM P 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 MPv2c with SN MPv3 This MIB is only useful if SNM Pv1 or SN M Pv2c is used possibly in combination with SN M Pv3 e SNMP 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 as in the following example include_1ib snmp include SNMPv2 MIB hrl1 The initial values for the managed objects defined in these tables are read at startup from
202. y 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 currently uses the defalt auto save time of dets 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 hasa M nesia equivalent The argument NameDb is a tuple Name Db where Name is the 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 Simple N etwork M anagement Protocol SN M P 125 snmp local_db SNMP Reference Manual Common Data Types In the functions defined below the following types are used e NameDb Name Db e Name atom Db volatile persistent e RowIndex int e Cols Col Col Value Col int Value term where RowIndex denotes the last part of the OID that specifies the index of the row in tha table Cols is a list of

Simple Network Management Protocol (SNMP)

Contents

Download Pdf Manuals

Related Search

Related Contents