| blob | c348796439eaf93181bc32796e4f5e917692aa66 |
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <head>
7 </head>
9 <body>
35 <div style="top: 12px; height: 129px; left: 0px; text-align: center; width: 925px;" id="logo"><a name="home2"></a><a href="http://www.lua.org"><img style="border: 0px solid ; left: 0px; top: 6px; width: 115px; height: 118px; float: left;" id="lualogo" alt="www.lua.org" src="luasnmp2.png" hspace="20" /></a></div>
88 LuaSNMP - Reference</big></big> <br />
114 Simple
115 Network Management Access with Lua</h1>
141 </div>
168 <ul>
374 <ul>
632 <ul>
866 <li><a href="#snmp_asynch_getnext">snmp.as</a><a href="#snmp_asynch_getnext">ync</a><a href="#snmp_asynch_getnext">h_getnext</a></li>
918 <li><a href="#snmp_asynch_set">snmp.as</a><a href="#snmp_asynch_set">ync</a><a href="#Lorem">h_set</a></li>
970 <li><a href="#snmp_asynch_getbulk">snmp.as</a><a href="#snmp_asynch_getbulk">ync</a><a href="#Lorem">h_getbulk</a></li>
1048 <li><a href="#snmp_asynch_inform">snmp.as</a><a href="#snmp_asynch_inform">ync</a><a href="#Lorem">h_inform</a></li>
1179 </ul>
1220 <ul>
1341 </ul>
1368 <ul>
1423 </ul>
1457 <ul>
1505 </ul>
1532 <ul>
1809 </ul>
1830 <ul>
1849 </ul>
1880 <ul>
2002 </ul>
2029 <ul>
2070 </ul>
2146 </ul>
2276 </ul>
2302 </div>
2344 <ul>
2358 <li>SNMP set, get, getnext, getbulk and walk primitives for synchronous and asynchronous operation</li>
2379 <li>SNMP view based access methods (VACM) management: map security
2380 names to security groups, create/delete views, create /
2409 <li>Miscellaneous helper functions, like result checking, sorting interator function</li>
2423 </ul>
2432 snmp.open([CONFIG])</h4>
2458 <p>The Function <i style="font-weight: bold; font-style: italic;">snmp.open</i><span style="font-weight: bold; font-style: italic;"> </span>is
2459 used for creating, or opening, <a href="objects.html#sessions" target="content">SNMP sessions</a>. It is a Lua<i>
2460 constructor</i>
2461 that validates the provided session configuration parameters given as a
2463 creates a
2464 Lua table for storing them, and allocates resources for controlling the
2465 SNMP operations invoked for the session. Default values are used when
2466 one, or more, configuration parameters are omitted.</p>
2492 <p>Default values are provided by the following sources with the
2493 stated precedence:</p>
2519 <ol>
2572 manual page for details)</li>
2624 </ol>
2676 <ul>
2884 </ul>
2910 <p>All other unconfigured parameters are either set to nil or
2937 <p>If a new
2938 Shttp://lua-users.org/lists/lua-l/http://lua-users.org/lists/lua-l/http://lua-users.org/lists/lua-l/NMP
2939 session is successfully created, <i><span style="font-weight: bold;">snmp.open</span> </i>returns
2940 a reference to this session. The
2941 returned reference must be specified as a handle in all invocations of
2942 SNMP
2943 operations for the session.</p>
2969 <p>If the provided configuration is invalid or an Net-SNMP
2970 internal error occurs, no session is created. In this case, <i><span style="font-weight: bold;">snmp.open </span> </i>returns
2972 message.</span></p>
2998 <p>Note, that all SNMP set and get functions are also mapped to a
2999 successfully created session, which allows to perform SNMP requests as
3000 a direct method call to a session. See also below.</p>
3026 <p>The following example illustrates the creation of an SNMP
3027 session
3028 that can be used by a management application for invoking SNMP
3029 operations on the agent identified by its host name <span style="font-style: italic;">"goofy"</span>. All
3030 SNMP messages sent to the agent will use the community string <span style="font-style: italic;">"private"</span>.
3031 SNMP version 2c (default value). A user-defined
3033 will be called whenever an SNMP trap originated by this agent is
3034 received. Another user defined function <span style="font-style: italic;">default_cb</span> is called for asynchronous requests (see <a style="font-style: italic;" href="#snmp_async_get">snmp.asynch_get</a>) </p>
3060 <pre>hub1, err = snmp.open{<br /> peer = "goofy", <br /> community = "private", <br /> trap = trap_cb,<br /> callback = default_cb,<br />}<br />assert(hub1, err)</pre>
3084 snmp.clone(PARENT [, CONFIG])<br />
3107 session, err = PARENT:clone([CONFIG])</h4>
3130 <p>Clones a valid session. The new session inherits all
3131 configuration parameters from it's parent session <span style="font-weight: bold;">PARENT</span>. If a
3132 configuration table CONFIG is provided, this configuration table
3133 overrides the parent's configuration.</p>
3159 <p>After successful creation the new session is completely
3160 independent from the parent session. In case of an error, the function <span style="font-style: italic; font-weight: bold;">snmp.clone </span><span style="font-style: italic;"></span>returns <span style="font-weight: bold;">nil</span> and an <span style="font-weight: bold;">error message</span>.</p>
3186 <pre>hub2, err = snmp.clone(hub1, {peer = "localhost"})<br />assert(hub2, err)<br />-- or simpler<br />hub2, err = hub1:clone{peer = "localhost"}<br />-- or event simpler including error handling<br />hub2 = assert(hub1:clone{peer = "localhost"})<br /></pre>
3265 <p>Returns the SNMP version of the given SESSION as string. If
3266 the
3267 session does not exist or does not own a valid valid version
3268 configuration parameter, the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>.</p>
3295 snmp.gettrapd()</h4>
3321 <p>Returns a string with the name of the trapdaemon for which
3322 LuaSNMP
3323 has been configured during compile time. The string contains either
3351 snmp.close(SESSION)<br />
3377 err = SESSION:close()</h4>
3403 <p>Terminates an active SNMP session. The function receives the <span style="font-weight: bold;">SESSION </span>previously
3404 created by snmp.open or snmp.close as handle<span style="font-weight: bold;">.</span> The function
3405 returns <span style="font-weight: bold;">1 </span>on success. In case of an error the function returns an <span style="font-weight: bold;">nil </span>plus an<span style="font-weight: bold;"> </span><span style="font-weight: bold;">error message</span>.</p>
3431 <p>In the following example, the SNMP session previously
3432 described is terminated.</p>
3458 <pre>-- Form 1<br />err = snmp.close(hub1)<br />-- Simplified form:<br />err = hub1:close()</pre>
3485 the sssion that
3486 shall be closed is waiting for an asynchronous request (either get or
3487 set) to complete, the session is not immediately closed, but put into a
3488 queue and will be closed once the request has completed. Any associated
3489 callback function (either default or request specific) is called before
3490 the session is actually closed and all it's data is garbage collected.</p>
3516 <p>Error codes returned by <span style="font-weight: bold; font-style: italic;">snmp.close</span> can be
3544 errindex = snmp.get(SESSION, VARS)<br />
3570 varbind, err, errindex = SESSION:get(VARS)<br />
3596 </h4>
3624 <p>The function <i><span style="font-weight: bold;">snmp.get </span> </i>is used to perform SNMP<i> get </i>operations
3625 for the specified <span style="font-weight: bold;">SESSION</span>. One or more MIB variable instances can be retieved by a single call. </p>
3651 <p>While <i style="font-weight: bold;">snmp.get </i>performs a <span style="font-style: italic;">synchronous</span> get operation which returns only when
3652 the operation completes, the function <a href="#snmp_async_get"><i style="font-weight: bold;">snmp.asynch_get</i></a>
3679 <p>The first argument <span style="font-weight: bold;">SESSION</span> is a reference to an SNMP session, returned from a previous call to <a href="#snmp_open" target="content"><i>snmp.open</i></a>
3682 identifies the MIB variable instance(s) to be retrieved.</p>
3707 <p>
3708 A <span style="font-weight: bold;">single MIB variable</span> instance can be identified by:</p>
3734 <p>
3735 A string containing either an object identifier (OID in dotted
3736 notation) or the name of the variable to be retrieved. Notice that an
3737 instance identifier must always be specified. As an example, both
3739 the current value of the MIB-II variable sysName.
3740 </p>
3766 <ul>
3793 as described in section <a href="objects.html#varbinds" target="content">Varbinds</a>.
3823 </ul>
3876 <ul>
3904 </li>
3930 <li>a <i>varbind list</i>, like <code>{{oid="sysName.0"},{oid="sysLocation.0"},{oid="1.3.6.1.2.1.1.5.0"}}</code></li>
3956 </ul>
3984 <p><span style="font-style: italic; font-weight: bold;">snmp.get </span>returns a <i style="font-weight: bold;">varbind table</i> or a <i style="font-weight: bold;">varbind
3985 list</i>, if the operation completes successfully. In case of errors <span style="font-style: italic;">detected locally</span> the function returns nil plus an error message. In case of errors <span style="font-style: italic;">detected by the agent</span> the returned varbind list may be empty<span style="font-weight: bold;"> </span>or may contain less values as requested, if one or more values
3986 couldn't be retrieved by the agent. Two additional values are then returned: a
3989 index</span> indicating the first instance that couldn't be
3990 retrieved.<br />
4016 </p>
4042 <p>If a varbind list is returned, each element of this varbind
4043 list is a fully specified varbind table.
4046 contain object identifiers in dotted notation.</p>
4072 <p>The following example illustrates the use of <i style="font-weight: bold;">snmp.get</i><span style="font-weight: bold; font-style: italic;"> </span> for retrieving
4074 group of MIB-II:</p>
4100 <pre>vlist, err, index = snmp.get(hub1, {"sysName.0","sysContact.0"}) <br />if not err then <br /> print(string.format("Contact for %s : %s", <br /> vlist[1].value, vlist[2].value)) <br />else <br /> if index then <br /> print(string.format("Error : %s in index %d", err, index)) <br /> else <br /> print(string.format("Error : %s", err)) <br /> end <br />end<br /></pre>
4124 <p>For convenience, LuaSNMP provides a means to perform SNMP requests in form of a <span style="font-weight: bold;">method call</span> to a valid session:</p>
4148 <pre>-- Request single varbind<br />vbind, err = hub1:get("sysContact.0")<br /><br />-- Request list of varbinds<br />vlist, err, index = hub1:get{"sysName.0","sysContact.0"}<br />...</pre>
4173 snmp.asynch_get(SESSION, VARS [,CALLBACK [,MAGIC]])<br />
4199 reqid, err = SESSION:asynch_get(VARS [,CALLBACK [,MAGIC]])</h4>
4223 <p>The function <span style="font-style: italic; font-weight: bold;">snmp.asynch_get </span> performs the same operation as
4224 <a href="#snmp_get"><span style="font-style: italic;">snmp.get</span></a>. However, instead of waiting for the request to complete, the
4226 message to the agent. When this request completes, a user-defined <span style="font-weight: bold;">CALLBACK</span> function
4252 present, it specifies a user-defined callback
4253 function to be invoked when the asynchronous operation completes. When
4254 this argument is omitted, the default callback
4255 function, specified when the SNMP session is created, is used.</p>
4279 <p>Each asynchronous operation can be associated with an opaque value <span style="font-weight: bold;">MAGIC</span>,
4280 which is transparently transported to the callback function. Note, that
4281 you can define a request specific magic value even if the request
4282 utilises the session's default callback function.</p>
4306 <p><b style="font-style: italic;">snmp.asynch_get </b><span style="font-style: italic;"> </span>returns a <span style="font-weight: bold;">number </span>containing the<i> </i>request id, if the request started successfully. If not, the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>.</p>
4334 table</span> (or a <span style="font-weight: bold;">varbind list</span>), a <span style="font-weight: bold;">string</span> containint the <span style="font-weight: bold;">error
4335 status</span> or <span style="font-weight: bold;">nil</span>, and an <span style="font-weight: bold;">error index</span>, if an error occurred.
4336 The fourth argument is a number with the <i style="font-weight: bold;">request-id</i><span style="font-weight: bold;"> </span>associated to
4337 the completed
4338 asynchronous request. The fifth argument contains a <span style="font-weight: bold;">reference to the
4339 SNMP session</span>. The last argument is the opaque magic value, which can be of any type. </p>
4361 <p>If no response is received, LuaSNMP performs the configured number
4362 of retries for the request. If none of these retries succeeds, the
4363 callback function is called with an error status indicating a timeout.
4364 </p>
4390 <p>The following example illustrates the use of <i style="font-weight: bold;">snmp.asynch_get</i><span style="font-style: italic; font-weight: bold;"> </span>
4391 in a very simple
4393 is called periodically. Based on
4399 request is completed. For simplicity,
4400 error conditions are mostly ignored.
4401 </p>
4427 <pre>local snmp = require "snmp"<br /><br />polled = {}<br />local count = 3<br /><br />local function poll_cb(vb, err, index, reqid, session, magic)<br /> local agent = polled[reqid]<br /> polled[reqid] = nil<br /> if vb then<br /> agent.status = "alive"<br /> else<br /> if err == "snmp: timeout" then<br /> agent.status = "no response"<br /> else<br /> agent.status = "?"<br /> end<br /> end<br /> count = count - 1<br />end<br /><br />function poll(agents)<br /> local i, agent = next(agents,nil)<br /> while i do<br /> local reqid = snmp.asynch_get(agent.session, <br /> "sysUpTime.0", poll_cb)<br /> if reqid then<br /> polled[reqid] = agent<br /> end<br /> i, agent = next(agents,i)<br /> end<br />end<br /><br />local agents = {<br /> { session = snmp.open{peer = "goofy"}, name = "goofy" }, <br /> { session = snmp.open{peer = "192.168.99.1"}, name = "192.168.99.1"}, <br /> { session = snmp.open{peer = "localhost"}, name = "localhost" }<br />}<br /><br /><br />poll(agents)<br />while count > 0 do <br /> snmp.event()<br />end<br /><br />for _, agent in ipairs(agents) do<br /> print(string.format("Agent status of %s: %s", <br /> agent.name, agent.status or 'failure'))<br /> agent.session:close()<br />end<br /></pre>
4449 <p>Since only the first value returned by <i style="font-weight: bold;">snmp.asynch_get </i><span style="font-weight: bold;"> </span>is necessary (the request-id),
4450 the remaining values can be discarded. Lua adjusts the list of returned
4451 values at run-time. Lua also dynamically adjusts the list of arguments
4453 and <span style="font-style: italic;">magic</span> arguments of the callback function are not used in this implementation,
4455 </p>
4504 errindex = snmp.getnext(SESSION, VARS)<br />
4530 varbind, err, errindex = SESSION:getnext(VARS)</h4>
4552 <p>The function <i style="font-weight: bold;">snmp.getnext </i>is used to perform SNMP<i> get-next </i>operations
4553 for the specified session. It retrieves the values of the lexicographical successors
4554 of a list of MIB objects.</p>
4576 <p>While <i style="font-weight: bold;">snmp.getnext</i><span style="font-style: italic; font-weight: bold;"> </span> performs a <span style="font-style: italic;">synchronous</span> get-next operation, which returns only when the operation completes, the function <a href="snmp_asynch_getnext"><i style="font-weight: bold;">snmp.asynch_getnext</i></a> operates asynchronously and returns immediately to the caller.</p>
4598 <p>The first argument <span style="font-weight: bold;">SESSION</span> is a reference to a valid SNMP session.
4599 The second argument <span style="font-weight: bold;">VARS</span> identifies one or more MIB <i>objects</i>. MIB objects are identified as described
4600 for <a href="#snmp_get" target="content"><i>snmp.get</i></a>. A single object is identified by a <i style="font-weight: bold;">string</i><span style="font-weight: bold;">
4601 </span>or by a <i style="font-weight: bold;">varbind table</i>, containing either an <i>object identifier</i> or a <i>MIB label</i>,
4603 Note that instance identifiers are not necessary.
4604 A list of objects is identified by a <span style="font-weight: bold;">list of strings</span> or by a <i style="font-weight: bold;">varbind list</i>.</p>
4625 <p><b style="font-style: italic;">snmp.getnext</b><span style="font-style: italic; font-weight: bold;"> </span> returns a <i style="font-weight: bold;">varbind table</i> or a <i style="font-weight: bold;">varbind list</i>, if the operation completes successfully. In case of errors <span style="font-style: italic;">detected locally</span> the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>. In case of errors <span style="font-style: italic;">detected by the agent</span> the returned varbind list may be empty<span style="font-weight: bold;"> </span>or may contain less values as requested, if one or more values
4626 couldn't be retrieved by the agent. Two additional values are then returned: a
4629 index</span> indicating the first instance that couldn't be
4630 retrieved.</p>
4652 <p>If a varbind list is returned, each element of this varbind
4653 list is a fully specified varbind table.
4655 tables returned by <i style="font-weight: bold;">snmp.getnext</i><span style="font-style: italic; font-weight: bold;"> </span> always
4656 contain object identifiers in dotted notation.</p>
4677 <p>The following example illustrates the use of <i style="font-weight: bold;">snmp.getnext </i>for retrieving the whole MIB tree
4678 implemented by an agent. </p>
4700 <pre>require "snmp"<br />hub1 = assert(snmp.open{peer = "goofy"})<br />repeat<br /> vb, err = snmp.getnext (hub1, vb or {oid = "1"})<br /> if not err and vb.type ~= snmp.ENDOFMIBVIEW then<br /> print(snmp.sprintvar(vb))<br /> end<br />until vb.type == snmp.ENDOFMIBVIEW</pre>
4721 <h4><a name="snmp_asynch_getnext"></a>reqid, err = snmp.asynch_getnext(SESSION, VARS, [,CALLBACK [,MAGIC]])<br />
4747 reqid, err = SESSION:asynch_getnext(VARS [,CALLBACK [, MAGIC]])</h4>
4768 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.asynch_getnext</span><span style="font-weight: bold;"> </span> performs the same operation as
4769 <a href="#snmp_getnext"><span style="font-style: italic;">snmp.getnext </span></a>. However, instead of waiting for the request to complete, the
4770 function returns immediately aft<span style="font-style: italic;"></span>er sending a <i>getnext-request</i>
4771 message to the agent. When this request completes, a user-defined <span style="font-weight: bold;">CALLBACK</span> function
4794 present, it specifies a user-defined callback
4795 function to be invoked when the asynchronous operation completes. When
4796 this argument is omitted, the default callback
4797 function, specified when the SNMP session is created, is used.</p>
4821 <p>Each asynchronous operation can be associated with an opaque value <span style="font-weight: bold;">MAGIC</span>,
4822 which is transparently transported to the callback function. Note, that
4823 you can define a request specific magic value even if the request
4845 <p><b style="font-style: italic;">snmp.asynch_getnext</b><span style="font-style: italic;"><span style="font-weight: bold;"> </span> </span>returns a <span style="font-weight: bold;">number </span>containing the<i> </i>request id, if the request started successfully. If not, the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>.</p>
4873 table</span> (or a <span style="font-weight: bold;">varbind list</span>), a <span style="font-weight: bold;">string</span> containint the <span style="font-weight: bold;">error
4874 status</span> or <span style="font-weight: bold;">nil</span>, and an <span style="font-weight: bold;">error index</span>, if an error occurred.
4875 The fourth argument is a number with the <i style="font-weight: bold;">request-id</i><span style="font-weight: bold;"> </span>associated to
4876 the completed
4877 asynchronous request. The fifth argument contains a <span style="font-weight: bold;">reference to the
4878 SNMP session</span>. The last argument is the opaque magic value, which can be of any type. </p>
4899 <p>If no response is received, LuaSNMP performs the configured number
4900 of retries for the request. If none of these retries succeeds, the
4901 callback function is called with an error status indicating a timeout.</p>
4922 <p>The following example illustrates an asynchronous version of the MIB traversal shown above.
4923 </p>
4944 <pre>require "snmp"<br /><br />local count = 0<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br /><br />function next_cb(vb, err, _, _, session)<br /> if not err and vb.type ~= snmp.ENDOFMIBVIEW then<br /> count = count + 1<br /> print(snmp.sprintvar(vb))<br /> session:asynch_getnext(vb, next_cb)<br /> else<br /> print(string.format("%d object instances retrieved", count))<br /> os.exit(0)<br /> end<br />end<br /><br />-- First call initialises retrieval of complete tree.<br />hub1:asynch_getnext("1", next_cb)<br />snmp.loop()<br /></pre>
4966 errindex = snmp.set(SESSION, VARBIND | VARLIST)<br />
4992 varbind, err, errindex = SESSION:set(VARBIND | VARLIST)</h4>
5013 <p>The function <i><span style="font-weight: bold;">snmp.set </span> </i>is used to perform SNMP<i> set </i>operations
5014 for the specified <span style="font-weight: bold;">SESSION</span>. One or more MIB variable instances can be modified by a single call. </p>
5041 <p>While <i style="font-weight: bold;">snmp.set</i><span style="font-style: italic; font-weight: bold;"> </span>
5042 performs a <span style="font-style: italic;">synchronous</span> set operation which returns only when
5043 the operation completes, the function <a href="snmp.html#snmp_async_get"><i style="font-weight: bold;">snmp.asynch_set</i></a>
5071 <p>The first argument <span style="font-weight: bold;">SESSION</span> is a reference to an SNMP session, returned from a previous call to <a href="snmp.html#snmp_open" target="content"><i>snmp.open</i></a>
5074 is varbind table. You can also specificy a varbind list <span style="font-weight: bold;">VARLIST</span>. See <a href="objects.html#varbinds">varbinds</a> for details. The <span style="font-weight: bold;">type</span> field is optional.</p>
5085 <p>The function returns the given varbind or varlist as returned by the SNMP agent. See <a href="#snmp_get">snmp.get</a> for more details. An <span style="font-weight: bold;">error message</span> is additionally returned in case of errors.</p>
5106 <p>The following example illustrates the use of <span style="font-style: italic; font-weight: bold;">snmp.set </span>:</p>
5127 <pre>local snmp = require "snmp"<br /><br />hub1, err = snmp.open{<br /> peer = "goofy", <br /> community = "private", <br />}<br />assert(hub1, err)<br /><br />vbIn = {<br /> {oid = "sysContact.0", value = "root"}, <br /> {oid = "sysLocation.0", value="MyHome"}<br />}<br />vbOut, err, index = hub1:set(vbIn)<br />assert(vbOut, err)<br />print(vbOut[1])<br />print(vbOut[2])</pre>
5148 <p>Note, that there is a metatable attached to the varbinds returned in
5149 the varbind list, which allows to convert the varbind into a readable
5150 string using the <span style="font-style: italic;">tostring </span> Lua function, which is implicitly called by
5151 print. Here is the output of the script above: </p>
5172 <pre>luasnmp$ lua doc/examples/set.lua<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />SNMPv2-MIB::sysLocation.0 = STRING: MyHome</pre>
5193 <h4><a name="snmp_asynch_set"></a>reqid, err = snmp.asynch_set(SESSION, VARBIND | VARLIST [,CALLBACK [, MAGIC]])<br />
5219 reqid, err = SESSION:set(VARBIND | VARLIST [,CALLBACK [, MAGIC]])</h4>
5240 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.asynch_get </span> performs the same operation as
5241 <span style="font-style: italic;">snmp.get</span>. However, instead of waiting for the request to complete, the
5243 message to the agent. When this request completes, a user-defined <span style="font-weight: bold;">CALLBACK</span> function
5265 <p>Refer to <a href="#snmp_async_get"><span style="font-style: italic; font-weight: bold;">snmp.asynch_get</span></a> for more details on asychronous operation.</p>
5307 varbind, err = SESSION:getbulk(NR, MR, VARS)</h4>
5328 <p>The functions <i style="font-weight: bold;">snmp.getbulk </i> performs a SNMPv2 <i>get-bulk </i>operation for the specified session.
5331 The difference is that, by using <i>get-bulk</i> operations, multiple lexicographical successors of
5332 a MIB object can be retrieved in a single protocol operation.
5333 </p>
5355 <p>While <i style="font-weight: bold;">snmp.getbulk</i><span style="font-weight: bold; font-style: italic;"> </span> performs a <span style="font-style: italic;">synchronous</span> <span style="font-style: italic;">get-bulk</span> operation, which returns only when the operation completes, the function <a href="snmp_asynch_getbulk"><i style="font-weight: bold;">snmp.asynch_getbulk</i></a> operates asynchronously and returns immediately to the caller.<br />
5376 </p>
5397 <p>The first argument <span style="font-weight: bold;">SESSION</span> of <i style="font-weight: bold;">snmp.getbulk </i> is a reference to a valid SNMP session.
5399 <a href="#snmp_getnext" target="content"><i>snmp.getnext</i></a> (a list of <span style="font-weight: bold;">strings</span> or a <i style="font-weight: bold;">varbind list</i>).
5400 The other two arguments, <span style="font-weight: bold;">NR</span> and <span style="font-weight: bold;">MR</span>, specify the number of lexicographical
5401 successors to be retrieved in the following way:
5402 </p>
5423 <ul>
5445 object in the <span style="font-weight: bold;">VARS</span> list, for which a <i style="font-weight: bold;">single</i> successor is returned.</li>
5467 for each of the remaining objects in the <span style="font-weight: bold;">VARS</span> list.</li>
5488 </ul>
5511 <p><b style="font-style: italic;">snmp.getbulk </b> returns a <i style="font-weight: bold;">varbind table</i> or a <i style="font-weight: bold;">varbind list</i>, if the operation completes successfully. In case of errors <span style="font-style: italic;">detected locally</span> the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>. In case of errors <span style="font-style: italic;">detected by the agent</span> the returned varbind list may be empty<span style="font-weight: bold;"> </span>or may contain less values as requested, if one or more values
5512 couldn't be retrieved by the agent. Two additional values are then returned: a
5515 index</span> indicating the first instance that couldn't be
5516 retrieved.</p>
5538 <p>If a <span style="font-weight: bold;">varbind list</span> is returned, each element of this varbind
5539 list is a fully specified varbind table.
5542 contain object identifiers in dotted notation.</p>
5563 <p>The following example illustrates the use of <i>snmp_getbulk</i>. A single invokation of <i>snmp_getbulk</i> retrieves the
5564 description and type of the first three interfaces of the system. Note in this example the <i><b>nr</b></i> argument set to 0.
5565 </p>
5586 <pre>local snmp = require "snmp"<br /><br />local ifNum = 3<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br /><br />ifList, err, index = hub1:getbulk(0, ifNum, {"ifDescr","ifType"})<br />assert(ifList, err)<br /><br />local types = snmp.mib.enums("ifType")<br />i = 1; last=ifNum * 2<br />while i < last do<br /> print(ifList[i].value..": "..types[ifList[i+1].value])<br /> i = i + 2<br />end<br /><br />table.foreach(ifList, print)<br /></pre>
5628 <pre>luasnmp$ lua doc/examples/getbulk.lua<br />lo: softwareLoopback<br />eth0: ethernetCsmacd<br />eth1: ethernetCsmacd<br />1 IF-MIB::ifDescr.1 = STRING: lo<br />2 IF-MIB::ifType.1 = INTEGER: softwareLoopback(24)<br />3 IF-MIB::ifDescr.2 = STRING: eth0<br />4 IF-MIB::ifType.2 = INTEGER: ethernetCsmacd(6)<br />5 IF-MIB::ifDescr.3 = STRING: eth1<br />6 IF-MIB::ifType.3 = INTEGER: ethernetCsmacd(6)</pre>
5649 <h4><a name="snmp_asynch_getbulk"></a>reqid, err = snmp.asynch_getbulk(SESSION, NR, MR, VARS, [,CALLBACK [,MAGIC]])<br />
5670 reqid, err = SESSION:asynch_getbulk(VARS, NR, MR [,CALLBACK [, MAGIC]])</h4>
5691 <p>The function <span style="font-style: italic; font-weight: bold;">snmp.asynch_getbulk </span> performs the same operation as
5692 <span style="font-style: italic;">snmp.getbulk</span>. However, instead of waiting for the request to complete, the
5694 message to the agent. When this request completes, a user-defined <span style="font-weight: bold;">CALLBACK</span> function
5717 present, it specifies a user-defined callback
5718 function to be invoked when the asynchronous operation completes. When
5719 this argument is omitted, the default callback
5720 function, specified when the SNMP session is created, is used.</p>
5744 <p>Each asynchronous operation can be associated with an opaque value <span style="font-weight: bold;">MAGIC</span>,
5745 which is transparently transported to the callback function. Note, that
5746 you can define a request specific magic value even if the request
5747 utilises the session's default callback function.</p>
5768 <p><b style="font-style: italic;">snmp.asynch_</b><span style="font-style: italic; font-weight: bold;">get</span><span style="font-style: italic;"><span style="font-weight: bold;">bulk </span> </span>returns a <span style="font-weight: bold;">number </span>containing the<i> </i>request id, if the request started successfully. If not, the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>.</p>
5796 table</span> (or a <span style="font-weight: bold;">varbind list</span>), a <span style="font-weight: bold;">string</span> containint the <span style="font-weight: bold;">error
5797 status</span> or <span style="font-weight: bold;">nil</span>, and an <span style="font-weight: bold;">error index</span>, if an error occurred.
5798 The fourth argument is a number with the <i style="font-weight: bold;">request-id</i><span style="font-weight: bold;"> </span>associated to
5799 the completed
5800 asynchronous request. The fifth argument contains a <span style="font-weight: bold;">reference to the
5801 SNMP session</span>. The last argument is the opaque magic value, which can be of any type. </p>
5822 <p>If no response is received, LuaSNMP performs the configured number
5823 of retries for the request. If none of these retries succeeds, the
5824 callback function is called with an error status indicating a timeout.</p>
5866 vlist, err, index = SESSION:walk(NODE)</h4>
5888 uses get-next SNMP primitives to query an agent for a tree of
5889 information. It behaves the same way as the NetSNMP command snmpwalk(1)
5911 <p>The first parameter <span style="font-weight: bold;">SESSION</span> is the reference to a valid SNMP session. The second parameter <span style="font-weight: bold;">NODE</span> specifies which portion of the object identifier space will be searched. If <span style="font-weight: bold;">NODE</span> is not specified snmp.walk will search in <span style="font-style: italic;">SNMPv2-MIB::mib-2</span>.</p>
5932 <p>The function returns a list of varbinds, if the operation succeeds.
5933 In case of an error the list of varbinds may be nil or partially
5934 filled. An <span style="font-weight: bold;">error message</span> is additionally returned.</p>
5955 <p>Here is an example that prints a list of interface types for all interfaces present in the system:</p>
5976 <pre>require "snmp"<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br /><br />vlist = assert(hub1:walk("ifType"))<br />table.foreach(vlist, function(k,v) print(v) end)<br /></pre>
6018 <pre>IF-MIB::ifType.1 = INTEGER: softwareLoopback(24)<br />IF-MIB::ifType.2 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.3 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.4 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.5 = INTEGER: tunnel(131)<br /></pre>
6040 uses get-next requests starting with the OID
6043 include the OID specified in the NODE parameter on the commandline,
6044 configure the session with the parameter <span style="font-style: italic; font-weight: bold;">includeroot = true.</span></p>
6086 <pre>IF-MIB::ifType = No Such Instance currently exists at this OID<br />IF-MIB::ifType.1 = INTEGER: softwareLoopback(24)<br />IF-MIB::ifType.2 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.3 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.4 = INTEGER: ethernetCsmacd(6)<br />IF-MIB::ifType.5 = INTEGER: tunnel(131)<br /></pre>
6107 <p></p>
6128 <h4><a name="snmp_inform"></a>vlist, err, errindex = snmp.inform(SESSION, TRAPOID, VARLIST)<br />
6149 vlist, err, errindex = SESSION:inform(TRAPOID, VARLIST)</h4>
6192 performs a <span style="font-style: italic;">synchronous</span> set operation which returns only when
6193 the operation completes, the function <a href="snmp.html#snmp_async_inform"><i style="font-weight: bold;">snmp.asynch_inform</i></a>
6216 defines a valid SNMP session, which must have been configured to send
6217 on a port on which a trap sink listens for traps. This will be
6218 typically port 162. The second parameter <span style="font-weight: bold;">TRAPOID</span> identifies the trap to be sent. The third parameter VARLIST is a <span style="font-weight: bold;">varbind list</span> containing additional information for the recipient.</p>
6260 <pre>require "snmp"<br /><br />hub1 = assert(snmp.open{peer = "localhost"})<br />hub1trap = hub1:clone{port = 162}<br /><br />local vlist = assert(hub1:get{"sysContact.0", "sysUpTime.0"})<br />local result, err = hub1trap:inform("sysName.0", vlist)<br />table.foreach(result, print)<br /></pre>
6302 <pre>luasnmp$ lua doc/examples/inform.lua<br />DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (0) 0:00:00.00<br />SNMPv2-MIB::snmpTrapOID.0 = OID: SNMPv2-MIB::sysName.0<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (5199693) 14:26:36.93<br /></pre>
6323 <h4><a name="snmp_asynch_inform"></a>reqid, err = snmp.asynch_inform(SESSION, TRAPOID, VARLIST [,CALLBACK [, MAGIC]])<br />
6344 reqid, err = SESSION:asynch_inform(TRAPOID, VARLIST [,CALLBACK [, MAGIC]])</h4>
6365 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.asynch_inform </span>performs the same operation as
6366 <span style="font-style: italic;"><a style="font-weight: bold;" href="#snmp_inform">snmp.inform</a>.</span> However, instead of waiting for the request to complete, the
6368 message to the agent. When this request completes, a user-defined <span style="font-weight: bold;">CALLBACK</span> function
6391 present, it specifies a user-defined callback
6392 function to be invoked when the asynchronous operation completes. When
6393 this argument is omitted, the default callback
6394 function, specified when the SNMP session is created, is used.</p>
6418 <p>Each asynchronous operation can be associated with an opaque value <span style="font-weight: bold;">MAGIC</span>,
6419 which is transparently transported to the callback function. Note, that
6420 you can define a request specific magic value even if the request
6421 utilises the session's default callback function.</p>
6442 <p><b style="font-style: italic;">snmp.asynch_</b><span style="font-style: italic; font-weight: bold;">inform </span><span style="font-style: italic;"><span style="font-weight: bold;"></span> </span>returns a <span style="font-weight: bold;">number </span>containing the<i> </i>request id, if the request started successfully. If not, the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span>.</p>
6470 table</span> (or a <span style="font-weight: bold;">varbind list</span>), a <span style="font-weight: bold;">string</span> containint the <span style="font-weight: bold;">error
6471 status</span> or <span style="font-weight: bold;">nil</span>, and an <span style="font-weight: bold;">error index</span>, if an error occurred.
6472 The fourth argument is a number with the <i style="font-weight: bold;">request-id</i><span style="font-weight: bold;"> </span>associated to
6473 the completed
6474 asynchronous request. The fifth argument contains a <span style="font-weight: bold;">reference to the
6475 SNMP session</span>. The last argument is the opaque magic value, which can be of any type. </p>
6496 <p></p>
6538 err = SESSION:wait()</h4>
6559 <p>The function snmp.wait waits until all asynchronous events pending for the given <span style="font-weight: bold;">SESSION</span>
6560 have completed. The function receives a reference to a valid SESSION as
6562 pending events of the GIVEN session have completed, responses of other
6563 session are processed as well.</p>
6584 <p>The example script and it's output show the behaviour of snmp.wait.
6585 During the wait phase of hub1 the first request of hub2 is also
6586 processed. Since there is only one request from hub1, <span style="font-style: italic;">hub1:wait </span> completes after this and the second request of hub2 is process during <span style="font-style: italic;">hub2:wait </span></p>
6607 <pre>local snmp = require "snmp"<br /><br />function func_cb(vb, status, index, reqid, session, magic)<br /> if magic == "goofy" then<br /> print("Callback: from goofy")<br /> else<br /> print("Callback: from localhost")<br /> end<br /> print(vb)<br />end<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br />hub2 = assert(hub1:clone{peer = "localhost"})<br /><br />local reqid1 = hub1:asynch_get("sysContact.0", func_cb, "goofy")<br />local reqid2 = hub2:asynch_get("sysContact.0", func_cb, "localhost")<br />local reqid2 = hub2:asynch_get("sysName.0", func_cb, "localhost")<br /><br />print("Waiting for hub1 ...")<br />hub1:wait()<br />print("Waiting for hub2 ...")<br />hub2:wait()<br /></pre>
6649 </p>
6670 <pre>luasnmp$ lua doc/examples/wait.lua<br />Waiting for hub1 ...<br />Callback: from localhost<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />Callback: from goofy<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />Waiting for hub2 ...<br />Callback: from localhost<br />SNMPv2-MIB::sysName.0 = STRING: goofy</pre>
6712 snmp.loop()</h4>
6733 <p>The function snmp.loop or snmp.idle provides an event loop. A
6734 LuaSNMP scripts remains in snmp.loop as long as there are uncompleted
6735 asynchronous operations and as long as there is a session with a trap
6736 callback function waiting for trap notifications. The function returns,
6737 when all asynchronous requests are completed and all trap capturing
6738 sessions have been closed.</p>
6780 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.event</span> checks for incoming responses from agents.
6781 It does NOT wait for responses. The function is useful in case you want
6782 to wait for different events (e.g. from a GUI) in a single loop.</p>
6803 <pre>while true do<br /> - Look for SNMP responses and invoke callback functions accordingly.<br /> snmp.event()<br /> - Wait for events from other packages<br /> ...<br />end<br /></pre>
6839 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.createuser</span> creates a new SNMPv3 <span style="font-weight: bold;">USER</span> on the remote machine, which is reachable via the given <span style="font-weight: bold;">SESSION</span>. The newly created user will not be active until an existing <span style="font-weight: bold;">CLONEFROM</span> user has been assigned to USER. Cloning assigns authentication parameters from the existing user <span style="font-weight: bold;">CLONEFROM</span> to <span style="font-weight: bold;">USER</span>. This can happen in 2 ways:</p>
6850 <ul>
6861 <li>Define a second user CLONEFROM when creating USER via <a href="#snmp_createuser">snmp.createuser</a></li>
6872 <li>Define the CLONEFROM in a second step using the function <a href="#snmp_clonefrom">snmp.clonefromuser</a></li>
6883 </ul>
6894 <p>The function returns a varbind (CLONEFROM omitted) containing the object <span style="font-weight: bold; font-style: italic;">usmUserStatus</span> or a varlist containing the objects <span style="font-weight: bold; font-style: italic;">userCloneFrom</span> and <span style="font-weight: bold; font-style: italic;">userSecurityName</span>. If an error occurs the varbind or varlist may be incomplete or <span style="font-weight: bold;">nil</span> and the function also returns an <span style="font-weight: bold;">error message</span>.</p>
6914 <pre>local snmp = require "snmp"<br />local mib = snmp.mib<br /><br />--<br />-- We will use this frequently<br />--<br />local check = snmp.check<br /><br />--<br />-- Lets define a convenient print function<br />--<br />function printf(fmt, ...)<br /> print(string.format(fmt, unpack(arg)))<br />end<br /><br />--<br />-- User to create<br />--<br />local user = "popey"<br /><br />--<br />-- User to clone from<br />--<br />local clonefromuser = "ronja"<br /><br />--<br />-- Open a working session<br />--<br />local sess, err = snmp.open{<br /> peer = "goofy",<br /> version = snmp.SNMPv3,<br /> user = "leuwer",<br /> password = "leuwer2006"<br />}<br />check(sess, err)<br /><br />--<br />-- Create the user 'popey'<br />--<br />local vl, err = check(sess:createuser(user, clonefromuser))<br />for _,v in ipairs(vl) do print(v) end<br /><br />--<br />-- Read and print popey's usmUserStatus<br />--<br />print(check(sess:get(mib.oid("usmUserStatus") .. snmp.instance(sess.contextEngineID, user))))<br /><br />--<br />-- Delete the user again<br />--<br />local vb, err = check(sess:deleteuser(user))<br /><br />--<br />-- Read and print popey's usmUserStatus<br />--<br />print(check(sess:get(mib.oid("usmUserStatus") .. mib.instance(sess.contextEngineID, user))))<br /><br />--<br />-- Close the working session<br />--<br />check(not sess:close())</pre>
6925 <h4><a name="snmp_clonefrom"></a>varlist, err = snmp.clonefromuser(SESSION, USER, CLONEFROM)</h4>
6936 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.clonefromuser</span> clones authentication parameters from an exisiting and active user <span style="font-weight: bold;">CLONEFROM</span> to a newly created <span style="font-weight: bold;">USER</span>. Note, that both users must exist before <span style="font-weight: bold; font-style: italic;">snmp.clonefromuser</span> is called.</p>
6947 <p>The function returns a varlist containing the objects <span style="font-weight: bold; font-style: italic;">userCloneFrom</span> and <span style="font-weight: bold; font-style: italic;">userSecurityName</span>. If an error occurs the varlist may not be complete or even <span style="font-weight: bold;">nil</span> and the function also returns an <span style="font-weight: bold;">error message</span>.</p>
6969 <p>The function <span style="font-weight: bold;">snmp.deleteuser</span> deletes the given <span style="font-weight: bold;">USER</span> on the remote machine that is reachable via the given <span style="font-weight: bold;">SESSION</span>. The user to be deleted may be in any state. </p>
6980 <p>The function returns a the object <span style="font-weight: bold; font-style: italic;">usmUserStatus</span> as varbind, with a <span style="font-style: italic; font-weight: bold;">value = snmp.rowStatus.destroy</span>. If an error occurs varbind may be nil or incomplete. An <span style="font-weight: bold;">error message</span> is additionally returned. </p>
6994 <h4><a name="snmp_newpassword"></a>varlist, err = snmp.newpassword(SESSION, OLDPW, NEWPW, FLAG, USER)</h4>
7008 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.newpassword</span> changes an SNMPv3 user's password in a remote machine, which is reachable via the given <span style="font-weight: bold;">SESSION</span>. The password of the given <span style="font-weight: bold;">USER</span> is changed from <span style="font-weight: bold;">OLDPW</span> to <span style="font-weight: bold;">NEWPW</span>. The optional parameter flag takes one of the following values </p>
7022 <ul>
7078 </ul>
7092 <p>If <span style="font-weight: bold;">USER</span> is omitted, the password of the given <span style="font-weight: bold;">SESSION</span> user is changed.</p>
7106 <p>Upon success the function returns a varlist containing the
7107 corresponding key change objects. In case of any error an
7121 <p>Note, that previous session based on OLDPW become unusable after
7122 changing the password. Any request using such a session results in an
7123 authentication error. To continue work with the changed password a new
7150 <pre>local snmp = require "snmp"<br /><br />-- User who's password to change<br />local user = "ronja"<br /><br />-- Old an new passwords<br />local oldpw = "ronja2006"<br />local newpw = "mydog2006"<br /><br />--<br />-- Create a work session which we use to change the password<br />--<br />local sess, err = snmp.open{<br /> peer = "goofy",<br /> version = snmp.SNMPv3,<br /> user = "leuwer",<br /> password = "leuwer2006"<br />}<br /><br />--<br />-- Create an "old" session using OLDPW<br />--<br />local sessold = assert(snmp.open{<br /> peer = "localhost",<br /> version = snmp.SNMPv3,<br /> user = user,<br /> password = oldpw})<br /><br />--<br />-- Change password implicit using the user's session.<br />--<br />local vl = assert(sessold:newpassword(oldpw, newpw, "a"))<br />for _,v in ipairs(vl) do print(v) end<br /><br />--<br />-- Create a "new" session using NEWPW for the user<br />--<br />local sessnew = assert(sessold:clone{password = newpw})<br /><br />--<br />-- Use the "new" session<br />--<br />print(assert(sessnew:get("sysContact.0")))<br /><br />--<br />-- Change password back from NEWPW to OLDPW explicitly<br />-- using the worker session<br />--<br />vl = assert(sess:newpassword(newpw, oldpw, "a", user))<br />for _,v in ipairs(vl) do print(v) end<br /><br />--<br />-- Reopen the old session. This will reuse OLDPW.<br />--<br />sessold2 = assert(sessold:clone())<br /><br />--<br />-- Use the reopened session<br />--<br />vb = assert(sessold2:get("sysContact.0"))<br />print(vb)<br /><br />--<br />-- Close all sessions created<br />--<br />assert(not sessold:close())<br />assert(not sessnew:close())<br />assert(not sessold2:close())<br />assert(not sess:close())<br /></pre>
7157 <br />
7164 <h4><a name="snmp_createkey"></a>key, keylen = snmp.createkey(SESSION, PASSWORD [,HASHTYPE])</h4>
7177 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.createkey </span>creates an authentication key from a given PASSWORD according to RFC 2274. The generator uses the algorithm defined in <span style="font-weight: bold;">HASHTYPE</span> for key generation. I this parameter is omitted, the function determines the hash type from the given <span style="font-weight: bold;">SESSION</span>.</p>
7190 <p>The function returns the key as Lua <span style="font-weight: bold;">string</span> (note, that this string may contain embedded zeros) and the length of the key as <span style="font-weight: bold;">number</span>. In case of errors the function return a <span style="font-weight: bold;">nil</span> key and an <span style="font-weight: bold;">error message</span> in keylen.</p>
7216 <ul>
7229 <li>MD5: use <span style="font-weight: bold;">snmp.usmProtocol.HMACMD5Auth </span>for HASHTYPE</li>
7242 </ul>
7255 <ul>
7268 <li>SHA1: use <span style="font-weight: bold;">snmp.usmProtocol.HMACSHA1Auth </span>for HASHTYPE</li>
7281 </ul>
7294 <p>This function is internally used in higher level USM management routines like <a href="#snmp_newpassword">snmp.newpassword</a>.</p>
7320 <h4><a name="snmp_createlocalkey"></a>key, keylen = snmp.createlocalkey(SESSION, KEY [,HASHTYPE] [,ENGINEID])</h4>
7333 <p>The function <span style="font-style: italic; font-weight: bold;">snmp.createlocalkey</span> creates a localised form of <span style="font-weight: bold;">KEY</span> at <span style="font-weight: bold;">ENGINEID</span> according to RFC2274. <span style="font-weight: bold;">KEY</span> is a Lua <span style="font-weight: bold;">string</span> containing an authentication key produced by <a href="#snmp_createkey">snmp.createkey</a>. The generator uses the algorithm defined in <span style="font-weight: bold;">HASHTYPE</span> for key generation (see <a href="snmp.html#snmp_createkey">snmp.createkey</a>) . I this parameter is omitted, the function determines the hash type from the given <span style="font-weight: bold;">SESSION</span>. The context engine ID is either explicitly defined as <span style="font-weight: bold;">ENGINEID</span> or taken from the given <span style="font-weight: bold;">SESSION</span>. </p>
7346 <p>The function returns the key as Lua <span style="font-weight: bold;">string</span> (note, that this string may contain embedded zeros) and the length of the key as <span style="font-weight: bold;">number</span>. In case of errors the function return a <span style="font-weight: bold;">nil</span> key and an <span style="font-weight: bold;">error message</span> in keylen.</p>
7359 <p>This function is internally used in higher level USM management routines like <a href="snmp.html#snmp_newpassword">snmp.newpassword</a>.</p>
7372 <h4><a name="snmp_keychange"></a>kcstring, kcstringlen = snmp.keychange(SESSION, OLDKEY, OLDKEYLEN, NEWKEY, NEWKEYLEN, [,HASHTYPE])</h4>
7385 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.keychange</span> uses <span style="font-weight: bold;">OLDKEY</span> and acquired random bytes to encode <span style="font-weight: bold;">NEWKEY</span> into <span style="font-weight: bold;">kcstring</span> and kcstringlen according to the rules of the KeyChange TC described in RFC 2274.</p>
7398 <p>This function is internally used to encode a password change from old to new in <a href="snmp.html#snmp_newpassword">snmp.newpassword</a>.</p>
7412 <h4><a name="vacm_sec2group"></a>varlist, err = snmp.createsectogroup(SESSION, SECMODEL, SECNAME, GROUPNAME)</h4>
7418 <p>The function <span style="font-style: italic; font-weight: bold;">snmp.createsectogroup</span> creates an entry in the security name to group table of a remote element reachable via a valid <span style="font-weight: bold;">SESSION</span>. The function receives the security model <span style="font-weight: bold;">SECMODEL</span> (<span style="font-weight: bold;">"SNMPv1", "SNMPv2" or "USM"</span>) and a security name <span style="font-weight: bold;">SECNAME</span> as <span style="font-weight: bold;">string</span> parameter. These two values are then used as index to create an entry for the group with name <span style="font-weight: bold;">GROUPNAME</span>, given as <span style="font-weight: bold;">string</span>.</p>
7424 <p>The group is later referenced by <a style="font-weight: bold; font-style: italic;" href="#vacm_createaccess">snmp.createaccess</a>.</p>
7430 <p>If the operation succeeds, <span style="font-weight: bold; font-style: italic;">snmp.createsectogroup</span> returns a <span style="font-weight: bold;">varlist</span> of two <a href="objects.html#varbinds">varbinds</a> containing the agent's response, which is <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::</span><span style="font-weight: bold;">vacmSecurityToGroupStatus</span> with value <span style="font-weight: bold; font-style: italic;">rowStatus.createAndGo</span> and <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::</span><span style="font-weight: bold;">vacmGroupName</span> carrying the group's name. In case of an error <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">error message</span> is returned indicating the type and location (varbind index in varlist) of the error.</p>
7436 <p>See <a href="#vacm_createaccess"><span style="font-weight: bold; font-style: italic;">snmp.createaccess</span></a> for a complete example on how to use the VACM functions.</p>
7443 <h4><a name="vacm_delete_sec2group"></a>varbind, err = snmp.deletesectogroup(SESSION, SECMODEL, SECNAME)</h4>
7449 <p>Deletes an entry in the name to group security table <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::</span><span style="font-weight: bold;">vacmSecuritytoGroupStatus</span> of a remote element addressed by SESSION. </p>
7455 <p>If the entry could be successfully deleted, the function returns a varbind containing <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::</span><span style="font-weight: bold;">vacmSecuritytoGroupStatus</span> set to <span style="font-weight: bold;">rowStatus.destroy</span>. In case of an error the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">errormessage</span>.</p>
7462 <h4><a name="vacm_createview"></a>varlist, err = snmp.createview(SESSION, VIEWNAME, SUBTREE, MASK [,FLAG])</h4>
7468 <p>The function <span style="font-weight: bold;">snmp.createview</span> creates a new entry in the <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::vacmViewTreeFamilyTable. </span>The parameter <span style="font-weight: bold;">VIEWNAME</span> is the name of the view. <span style="font-weight: bold;">SUBTREE</span> designates the root OID of the subtree that is added to the view. <span style="font-weight: bold;">MASK</span> is a bitmask that indicates which subidentifiers of the given tree are significant. The optional parameter <span style="font-weight: bold;">FLAG</span> is string that defines whether the SUBTREE is included (FLAG = <span style="font-weight: bold;">"inc(lude)"</span>) or excluded (FLAG=<span style="font-weight: bold;">"exc(lude)"</span>) from the view. The default is <span style="font-weight: bold;">"include"</span>.</p>
7474 <p>Upon success the function returns a varlist containing the new entry in <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::vacmViewTreeFamilyTable. <br />
7480 </span>The following objects of the entry are returned:
7481 vacmViewTreeFamilyStatus (createAndGo), vacmViewTreeFamilyMask (as
7483 an error occurs the function return <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">errormessage</span> indicating the first varbind in the varlist that failed.</p>
7489 <h4><a name="vacm_delete_view"></a>varbind, err = snmp.deleteview(SESSION, VIEWNAME, SUBTREE)</h4>
7495 <p>Deletes an entry in the view table <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::vacmViewTreeFamilyTable. </span>If the entry could be successfully deleted, the function returns a varbind containing <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::</span><span style="font-weight: bold;">vacmViewTreeFamilyStatus</span> set to <span style="font-weight: bold;">rowStatus.destroy</span>. In case of an error the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">errormessage</span>.</p>
7503 snmp.createaccess(SESSION, GROUPNAME, SECMODEL, SECLEVEL, CONTEXTMATCH,
7510 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.createaccess</span> creates an entry int the SNMPv3 access table <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::vacmAccessTable </span>of<span style="font-weight: bold;"> </span>the remote element reachable via the given SESSION.<span style="font-weight: bold;"> </span>The access writes are those described by the given <span style="font-weight: bold;">GROUPNAME</span>, <span style="font-weight: bold;">SECMODEL</span> and <span style="font-weight: bold;">SECLEVEL</span>. The parameter <span style="font-weight: bold;">CONTEXTMATCH</span>
7511 defines how the optionally given CONTEXTPREFIX is interpreted: either
7519 <p>The MIB scope is defined differently for read, write and notification access using the view names <span style="font-weight: bold;">READVIEW</span>, <span style="font-weight: bold;">WRITEVIEW</span> and <span style="font-weight: bold;">NOTIFYVIEW</span>. </p>
7525 <p>Upon success the function returns a varlist containing the new entry in <span style="font-weight: bold;">SNMP-VIEW-BASE-ACM-MIB::vacmAccessTable. </span>If an error occurs the function returns nil plus an <span style="font-weight: bold;">errormesage</span> indicating the first object with a failure in the varlist.</p>
7537 <pre>local snmp = require "snmp"<br />local mib = snmp.mib<br /><br />-- We will use this frequently - so let's have a local ref<br />local check = snmp.check<br /><br />--<br />-- Open a working session<br />--<br />local sess, err = check(snmp.open{<br /> peer = "localhost",<br /> version = snmp.SNMPv3,<br /> user = "leuwer",<br /> password = "leuwer2006",<br /> })<br />--<br />-- Create a user to give access to.<br />--<br />local vl = check(sess:createuser("olivia", "ronja"))<br /><br />--<br />-- The new user typically needs a new password. <br />--<br />vl = check(sess:newpassword("ronja2006", "gonzo2006", "a", "olivia"))<br /><br />--<br />-- Create security name to group mapping.<br />--<br />vl, err = sess:createsectogroup("usm", "olivia", "rwgroup")<br />if err then<br /> -- <br /> -- An error occurred: cleanup and delete the above new user here.<br /> --<br /> vl = check(sess:deleteuser("olivia"))<br /> sess:close()<br /> os.exit(1)<br />end<br /><br />--<br />-- Create a new view 'interfaces'<br />--<br />vl = check(sess:createview("interfaces", mib.oid("ifTable"), "80", "include"))<br /><br />--<br />-- Create a new access entry for the new group.<br />--<br />vl = check(sess:createaccess("rwgroup", "usm", "authNoPriv", "exact", <br /> "interfaces", "interfaces", "_none_"))<br /><br />--<br />-- Let's have a look at all this stuff<br />--<br />table.foreach(sess:walk("vacmAccessTable"), print)<br /><br />-- Finished: now we could test gos and nogos in the access.<br />-- Cleanup all newly created stuff.<br />--<br />vl = check(sess:deleteaccess("rwgroup", "usm", "authNoPriv"))<br />vl = check(sess:deleteview("interfaces", mib.oid("ifTable")))<br />vl = check(sess:deletesectogroup("usm", "olivia"))<br />vl = check(sess:deleteuser("olivia"))<br />sess:close()<br /></pre>
7543 <h4><a name="vacm_delete_access"></a>varbind, err = snmp.deleteaccess(SESSION, GROUPNAME, SECMODEL, SECLEVEL [,CONTEXTPREFIX]) </h4>
7550 <p>Deletes an entry in the <span style="font-weight: bold;">SNMP-VIEW-BASED-ACM-MIB::vacmAccessTable. </span>If
7551 the entry could be successfully deleted the function returns a varbind
7552 containing the table entry's row status set to destroy. In case of an
7553 error the function returns <span style="font-weight: bold;">nil</span> plus an <span style="font-weight: bold;">errormessage</span>.</p>
7598 <p>The function <span style="font-weight: bold; font-style: italic;">snmp.newvar</span> creates a new <a href="objects.html#varbinds">varbind</a> instance. <span style="font-weight: bold;">NAME</span>
7599 designates the SNMP node via a symbolic name or via an objects
7600 identifier in dotted notation. The varbind receives <span style="font-weight: bold;">VALUE</span> as its value. A <span style="font-weight: bold;">TYPE</span> can be optionally defined. If omitted, LuaSNMP determines the object type using the NAME and the global MIB tree.</p>
7613 <p> The optional parameter <span style="font-weight: bold;">SESSION</span> is stored in a hidden field and
7631 <p>LuaSNMP sets appropriate metamethods for the varbind table for printing, concatenation and arithmetic (see <a href="objects.html#varbinds">varbinds</a>).</p>
7648 <p>A typical usage of this function is the preparation of variable bindings for set-request operations.</p>
7689 result = snmp.sprintvar2(VAR)<br />
7709 result = SESSION.sprintvar(VAR)</h4>
7729 <p>Converts the given varbind <span style="font-weight: bold;">VAR</span> into a printable <span style="font-weight: bold;">string</span>. The function can be called either in <span style="font-weight: bold;">snmp</span> namespace or as a <span style="font-weight: bold;">method of a valid SNMP session</span>. The second method allows to override the function by specifiying the <span style="font-weight: bold;">sprintvar</span> configuration parameter during session creation.</p>
7747 <p><span style="font-weight: bold;">snmp.sprintvar2</span> is just another variant to convert a varbind to a printable string.</p>
7767 <p>Note, that you can also apply the standard Lua SNMP <span style="font-weight: bold; font-style: italic;">tostring</span> function to varbinds returned by LuaSNMP. See <a href="objects.html#varbinds"><span style="font-weight: bold;">Varbinds</span></a> for details.</p>
7807 <pre>local snmp = require "snmp"<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br /><br />vb = assert(hub1:get("sysContact.0"))<br />print("OUTPUT of 'sprintvar':")<br />print(vb)<br />print(snmp.sprintvar(vb))<br />print(hub1.sprintvar(vb))<br />print(snmp.sprintvar2(vb))<br />print()<br />print("OUTPUT of 'sprintval':")<br />print(snmp.sprintval(vb))<br />print(snmp.sprintval2(vb))<br />print()<br />print("OUTPUT of 'sprinttype':")<br />print(snmp.sprinttype(vb))<br />print(snmp.mib.typename(vb))<br /><br /></pre>
7827 <p>The above script generates the following output. Don't be confused
7828 about the relation Integer32 and STRING. This is caused by official
7829 SNMP typecodes and their translation into typenames.</p>
7849 <pre>luasnmp$ lua doc/examples/sprint.lua<br />OUTPUT of 'sprintvar':<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />SNMPv2-MIB::sysContact.0 = STRING: root<br />sysContact.0 (Integer32) = STRING: root<br /><br />OUTPUT of 'sprintval':<br />STRING: root<br />root<br /><br />OUTPUT of 'sprinttype':<br />Integer32<br />Integer32</pre>
7890 result = snmp.sprintval2(VAR)<br />
7910 result = SESSION.sprintval(VAR)</h4>
7930 <p>Converts the value of a given <span style="font-weight: bold;">VAR</span> into a printable string. See <a style="font-weight: bold; font-style: italic;" href="snmp_sprintvar">snmp.sprintvar</a> for details and an example.</p>
7970 </h4>
7990 <p>Converts the type of a given <span style="font-weight: bold;">VAR</span> into a printable string. See <a style="font-weight: bold; font-style: italic;" href="snmp_sprintvar">snmp.sprintvar</a> for details and an example.</p>
8012 str = snmp.key2octet(KEY [, LEN])<br />
8026 str = snmp.octetstring(KEY [, LEN])</h4>
8040 <p>Converts the string <span style="font-weight: bold;">KEY</span> containing any character code (even 0x00) into a OCTET STRING representation of the form <span style="font-style: italic; font-weight: bold;">01:02:0a:0b</span>. This representation can be used to set a string value with embedded zeros in a varbind. The optional parameter <span style="font-weight: bold;">LEN</span> defines how many
8041 characters are to evaluated. If omitted the whole string is converted.</p>
8069 <pre>luasnmp$ lua -l snmp -i<br />> key=string.char(1,2,3,4,5,10,11,12)<br />> =string.len(key)<br />8<br />> =snmp.octetstring(key)<br />01:02:03:04:05:0a:0b:0c<br />> =snmp.key2oid(key)<br />1.2.3.4.5.10.11.12<br />> =snmp.key2hex(key)<br />0x01020304050A0B0C<br />> return snmp.key2octet(key,6)<br />01:02:03:04:05:0a<br />> return snmp.key2octet(key,9)<br />01:02:03:04:05:0a:0b:0c<br /></pre>
8097 str = snmp.key2oid(KEY, LEN)</h4>
8111 <p>Converts the string <span style="font-weight: bold;">KEY</span> containing any character code (even 0x00) into an OID representation <span style="font-style: italic; font-weight: bold;">1.2.10.11</span>. The optional parameter <span style="font-weight: bold;">LEN</span> defines how many characters are to evaluated. If omitted the whole string is converted.</p>
8148 str = snmp.key2hex(KEY, LEN</h4>
8162 <p>Converts the string <span style="font-weight: bold;">KEY</span> containing any character code (even 0x00) into an hexadecimal readable representation<span style="font-style: italic; font-weight: bold;"> 0x01020A0B</span>. The optional parameter <span style="font-weight: bold;">LEN</span> defines how many characters are to evaluated. If omitted the whole string is converted.</p>
8210 result = snmp.uptimeS2V(TIME)</h4>
8230 <p>These functions convert SNMP timetick values into a formatted strings and vice versa. </p>
8250 <p><span style="font-weight: bold; font-style: italic;">snmp.uptimeV2S</span> receives a number containing <span style="font-weight: bold;">TICKS</span> and returns a formatted <span style="font-weight: bold;">string</span> containing the time human readable format.</p>
8270 <p>snmp.uptimeS2V receives a formatted string <span style="font-weight: bold;">TIME</span> and returns a table with the following fields:<br />
8290 days, hours, minutes, seconds, deciseonds and ticks.</p>
8330 <pre>local snmp = require "snmp"<br /><br />hub1 = assert(snmp.open{peer = "goofy"})<br /><br />vb = assert(hub1:get("sysUpTime.0"))<br />print(vb)<br /><br />time = snmp.uptimeV2S(vb.value)<br />ticks = snmp.uptimeS2V(time)<br /><br />print(time)<br />table.foreach(ticks, print)<br /></pre>
8370 <pre>luasnmp$ lua doc/examples/uptime.lua<br />DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (383697) 1:03:56.97<br />0:1:3:56.97<br />minutes 3<br />deciseconds 97<br />ticks 383697<br />hours 1<br />days 0<br />seconds 56<br /><br /></pre>
8387 <p>LuaSNMP provides the Finalized Exceptions concept designed by Diego Nehab for luasocket. See <a href="http://lua-users.org/wiki/FinalizedExceptions">here</a> for details. </p>
8394 into a safe function. This
8395 function only catches exceptions thrown by a try function - either
8396 the predefined snmp.try or a try function, that was newly created
8397 via <a href="#snmp_newtry"><span style="font-weight: bold; font-style: italic;">snmp.newtry</span></a>. It does not catch normal
8398 Lua errors.
8399 </p>
8407 <span style="font-weight: bold;">FUNCTION</span> is a function that calls try (or assert or error)
8408 to throw exceptions. Function <span style="font-weight: bold; font-style: italic;">snmp.protect</span> returns an equivalent function that instead of throwing exceptions,
8409 returns <tt><b>nil</b></tt> followed by an <span style="font-weight: bold;">error message.</span>
8410 </p>
8416 Note: Beware that if your function performs some illegal operation that
8417 raises an error, the protected function will catch the error and return it
8418 as a string. This is because the <span style="font-weight: bold; font-style: italic;">try</span> function
8419 uses errors as the mechanism to throw exceptions.
8420 </p>
8427 Creates and returns a <em>clean <span style="font-weight: bold;">try</span> </em>function that allows for cleanup before the exception
8428 is raised.
8429 </p>
8438 </p>
8444 The function <span style="font-weight: bold; font-style: italic;">snmp.newtry</span> returns your customized <tt>try</tt> function.</p>
8450 <pre>local snmp = require "snmp"<br />local mib = snmp.mib<br /><br />--<br />-- We need this reference here for the finalizer<br />--<br />local sess<br /><br />--<br />-- Finalize function<br />--<br />local function finalize()<br /> io.write("Cleanup handler: ")<br /> if sess then<br /> if rawget(sess, "internal") then<br /> print("closing session.")<br /> sess:close()<br /> else<br /> print("session already closed.")<br /> end<br /> else<br /> print("nothing to do.")<br /> end<br />end<br /><br />local function pdoit()<br /><br /> -- <br /> -- Acquire a new exception handler<br /> --<br /> local try = snmp.newtry(finalize)<br /><br /> --<br /> -- Do some work: no failure here<br /> --<br /> sess = try(snmp.open{peer = "goofy"})<br /> <br /> --<br /> -- Do some work: no failure here<br /> --<br /> local vl = try(sess:get{"sysContact.0","sysDescr.0"})<br /> table.foreach(vl, print)<br /><br /> --<br /> -- Do some work: no failure here<br /> --<br /> local vl = try(snmp.walk(sess, "ifDescr"))<br /> table.foreach(vl, print)<br /><br /> --<br /> -- Do some work: no failure here<br /> --<br /> local t = try(sess.ifDescr)<br /> for k,v in snmp.spairs(t) do print(k,v) end<br /><br /> --<br /> -- Close the session orderly. Note this will delete the<br /> -- internal session. Following usage must fail.<br /> --<br /> try(sess:close())<br /><br /> --<br /> -- Try to re-use the old session which should fail<br /> --<br /> local vl = try(snmp.walk(sess, "ifDescr"))<br /> table.foreach(vl, print)<br /><br /> return "ok"<br />end<br /><br />--<br />-- Execute the protected function 'pdoit'<br />--<br />local rv, err = snmp.protect(pdoit)()<br /><br />-- <br />-- Evaluate the result of error capturing<br />--<br />if not rv then<br /> print("doit error: '"..(err or "unknown").."'")<br />else<br /> print("doit o.k.")<br />end<br /></pre>
8456 <p>Throws an exception in case of an error in <span style="font-weight: bold;">RET1</span>. The exception can only be caught
8457 by the function <a href="#snmp_protect"><span style="font-weight: bold; font-style: italic;">snmp.protect</span></a>. If used outside a protected function, the Lua script is abortet WITHOUT error message or stack backtrace.
8458 </p>
8464 <tt></tt>The function receives an arbitrary number of arguments <span style="font-weight: bold;">RET1</span> to <span style="font-weight: bold;">RETn</span>, which are typically the returns values of a function call nested with snmp.try. The function returns <span style="font-weight: bold;">RET1</span> to <span style="font-weight: bold;">RETn</span> if <span style="font-weight: bold;">RET1</span> was not nil. Otherwise, it calls <span style="font-weight: bold; font-style: italic;">error</span> passing <span style="font-weight: bold;">RET2</span> as argument.
8465 </p>
8495 performs a check on the result of LuaSNMP functions. It works similar
8496 to the standard Lua function assert. However, instead of just checking <span style="font-weight: bold;">EXPRESSION</span>, snmp.check also checks whether <span style="font-weight: bold;">MESSAGE</span> is nil. It returns the given <span style="font-weight: bold;">EXPRESSION</span> only if the following two conditions are met: <span style="font-weight: bold; font-style: italic;">EXPRESSION == true and MESSAGE == nil</span>.</p>
8508 <p>The function is provided for convenience reasons, because there are
8509 conditions, where LuaSNMP will return both, a valid result AND an error
8510 message. For these cases Lua's standard <span style="font-weight: bold; font-style: italic;">assert</span> function is not suited to capture errors by simply writing result = assert(FUNCTION).</p>
8534 <pre>-- NOTE: DOES NOT WORK PROPERLY IN ALL CASES<br />vbind, err = assert(session:get(OBJECT))<br /><br />-- NOTE: THIS WORKS<br />vbind, err = session:get(OBJECT)<br />assert(vbind and not err, err)</pre>
8558 <pre>-- Do this once in the script<br />local check = snmp.check<br />...<br />-- NOTE: WORKS<br />vbind, err = check(session:get(OBJECT))<br />vbind, err = session:get(OBJECT)<br />check(vbind, err)<br /><br />-- NOTE: DOES NOT WORK, because MESSAGE will be always non-nil <br />vbind, err = session:get(OBJECT)<br />check(vbind, "Error occured here")</pre>
8570 <p>Note, that you MUST NOT specify your own error message to
8571 snmp.check, because this will always lead to an error condition (see
8572 example above).</p>
8602 <p>Retrieves a table with keys from a table, that has been created via <a href="#snmp_object_access">SNMP Object Access</a>. The keys are lexicographically sorted.</p>
8632 <pre>local snmp = require "snmp"<br /><br />-- Open the session<br />local hub, err = assert(snmp.open{peer="localhost"})<br /><br />-- Get a table or part of a table<br />local ifDescr = hub.ifDescr<br /><br />local keys = snmp.getkeys(ifDescr)<br /><br />-- Print using standard iterator<br />print("Using standard iterator:")<br />for k,v in pairs(ifDescr) do<br /> print(string.format("%s = %s", k, v))<br />end<br /><br />-- Print using sorting iterator<br />print("Using sorting iterator:")<br />for i,key in ipairs(keys) do<br /> print(string.format("%s = %s", key, ifDescr[key]))<br />end</pre>
8677 <p>The iterator <span style="font-weight: bold; font-style: italic;">snmp.spairs</span> works similar to the standard Lua operator
8678 pairs. However, instead of returning the elements of a table with
8679 arbitrary keys in arbitrary order (e.g. table as created via <a href="#snmp_object_access">SNMP Object Access</a>), it returns the elements in a lexicographically sorted order of their keys.</p>
8694 <pre>local snmp = require "snmp"<br /><br />-- Let's have a local reference to this function<br />local spairs = snmp.spairs<br /><br />-- Open the session<br />local hub, err = assert(snmp.open{peer="localhost"})<br /><br />-- Get a table or part of a table<br />local ifDescr = hub.ifDescr<br /><br />-- Print using standard iterator<br />print("Using standard iterator:")<br />for k,v in pairs(ifDescr) do<br /> print(string.format("%s = %s", k, v))<br />end<br /><br />-- Print using sorting iterator<br />print("Using sorting iterator:")<br />for k,v in spairs(ifDescr) do<br /> print(string.format("%s = %s", k, v))<br />end<br /><br /></pre>
8724 <pre>Using standard iterator:<br />ifDescr.3 = eth1<br />ifDescr.2 = eth0<br />ifDescr.4 = eth2<br />ifDescr.5 = sit0<br />ifDescr.1 = lo<br />Using sorting iterator:<br />ifDescr.1 = lo<br />ifDescr.2 = eth0<br />ifDescr.3 = eth1<br />ifDescr.4 = eth2<br />ifDescr.5 = sit0<br /></pre>
8744 oid = mib.instance(ARG1, ARG2, ..., ARGN)</h4>
8754 <p>Creates an oid instance substring from arguments ARG1 to ARGN. Each
8755 argument is converted into OID syntax. Single arguments are separated
8756 by a period '.'. Lua types are processed in the following way:</p>
8766 <ul>
8786 <li>string values are analysed whether the string contains an OID.
8787 If yes, the function returns that OID prepended by period '.'.
8788 Otherwise the string is encoded using the function <a style="font-weight: bold; font-style: italic;" href="#snmp_stringoid">snmp.stringoid</a>. The length of the string is prepended as single node.</li>
8798 <li>boolean values are encoded as single node, where false is encoded as 0 and true is encoded as 1</li>
8808 <li>tables are accepted and recursively interpreted as argument
8809 extension (via Lua <span style="font-style: italic;">unpack </span>function), where each value in the
8810 table represents a new argument.</li>
8820 </ul>
8840 <pre>luasnmp$ lua -l snmp -i<br />> =snmp.instance(99,"hello",true,{99,"hello",true})<br />.99.5.104.101.108.108.111.1.99.5.104.101.108.108.111.1<br />> =snmp.instance{1,2,3,4,5}<br />.1.2.3.4.5<br /></pre>
8857 snmp.instance with a string as argument. The only differences is that
8858 snmp.stringoid produces an absolute OID (without a leading '.'),
8889 where the object instances appear as members of an SNMP session. The
8890 method usese the Lua metamethods <span style="font-weight: bold;">__index</span> and <span style="font-weight: bold;">__newindex</span>
8891 attached to a session. Once a session has been successfully
8892 created, each read access to a session member is automatically
8893 translated to a read accesses to SNMP object instances with the
8894 given name. Also, any attempt to assign a value to a member is
8913 <p>The above works for single SNMP object instances and also
8914 for tables containing multiple object instances. Tables are always
8915 returned as simple Lua tables, where the key always represents a valid
8916 object identifier in symbolic notation and index instances appended.
8918 A returned table can be handled in two different ways. You can assign
8919 new values to table entries and then assign assign the table as value
8920 to the session member or you can use the indices of the table as single
8921 member names for assignment.</p>
8939 <p>here are a few aspects to consider if you want to use this simplified way of SNMP programming.</p>
8957 <ul>
8975 <li>If you use the form SESSION.instance any dot '.' in the instance name must be replaced with an underscore, e.g. <span style="font-weight: bold;">hub1.sysContact_0</span>. LuaSNMP will translate any underscored instance name into a dotted instance name.<br />
8993 Note, that the underscore is not required if the access occurs using the form <span style="font-weight: bold;">hub1["sysContact.0"]</span></li>
9011 <li>Direct object accesses do not return any type information. SNMP
9012 types are sliently translated into Lua types and vice versa. However,
9013 you don't have to care during write access. LuaSNMP will always use the
9014 correct type when writing to object instances.</li>
9032 <li>If you retrieve a complete table, the table indices cannot be
9033 expected to be sorted. However, it is easy to create a sorted table
9034 using Lua's <span style="font-weight: bold; font-style: italic;">table.sort </span> function</li>
9052 </ul>
9088 <pre>local snmp = require "snmp"<br /><br />hub1 = assert(snmp.open{peer = "goofy", community = "private"})<br /><br />-- Sets an re-stores sysContact.0<br />local oldval = hub1.sysContact_0<br />print("sysContact.0 = " .. hub1.sysContact_0)<br /><br />hub1.sysContact_0 = "admin"<br />print("sysContact.0 = " .. hub1["sysContact.0"])<br /><br />hub1["sysContact.0"] = oldval<br />print("sysContact.0 = " .. hub1.sysContact_0)<br /><br />-- Shows the list of interface names<br />itab = hub1.ifName<br />table.foreach(itab, print)<br /><br />-- Counts the number of objects in mib-2.<br />local mib2 = hub1["mib-2"]<br />sum = 0<br />for _,v in pairs(mib2) do<br /> sum = sum + 1<br />end<br />print("Number of entries in 'mib-2': " .. sum)</pre>
9124 <pre>luasnmp$ lua doc/examples/direct.lua<br />sysContact.0 = root<br />sysContact.0 = admin<br />sysContact.0 = root<br />ifName.1 lo<br />ifName.2 eth0<br />ifName.5 sit0<br />ifName.3 eth1<br />ifName.4 eth2<br />Number of entries in 'mib-2': 2389</pre>
9142 </div>
9168 <div id="footer">(c) 2006-2009 Herbert Leuwer, March 2006 <a href="mailto:herbert.leuwer@t-online.de">Contact</a></div>
9194 <small><small>
9195 </small></small>
9196 </body>
9197 </html>