README

   1
   2 LuaSNMP
   3 =======
   4
   5
   6 * LuaSNMP
   7   -------
   8
   9   LuaSNMP is a binding to the netsnmp library.
  10
  11   LuaSNMP is basically an update to the LuaMan library developed by
  12   Michele E. Lima and Ana Lucia de Moura (ana@telemidia.puc-rio.br).
  13
  14   LuaSNMP requires the net-snmp library version 5.6 or later. The netsnmp library
  15   can be downloaded from
  16           http://sourceforge.net/projects/net-snmp/
  17   See "* LuaSNMP under MS Windows" below for details on issues when using LuaSNMP
  18   with Microsoft Windows.
  19
  20   You must have Lua version 5.1, 5.2 or 5.3 to use it.
  21   Lua can be downloaded from its home page:
  22           http://www.tecgraf.puc-rio.br/lua/
  23
  24 * Documentation
  25   -------------
  26
  27   The original LuaMan documentation (up to version 2.3) can be reached
  28   from its home page:
  29           http://www.telemidia.puc-rio.br/~ana/luaman/
  30
  31   An updated documentation comes with the LuaSNMP distribution in the doc
  32   sub-directory.
  33
  34
  35 * Legal matters
  36   -------------
  37
  38   LuaSNMP is licensed under the MIT license.
  39
  40
  41 * Installation
  42   ------------
  43
  44   Note, that the makefile configuration defines Lua 5.2 as the default Lua version.
  45   In order to build LuaSNMP for other Lua versions you either have to change
  46   the variables V and LV in the makefile configuration file config or specify
  47   the destined Lua version in the command line, e.g. make V=53 LV=5.3.
  48
  49   In order to build LuaSNMP on a Linux, Unix or Cygwin/Mingw based
  50   POSIX like system:
  51
  52
  53   1. Make sure you have Lua (version 5.1 or later).
  54
  55   2. LuaSNMP comes with a makefile and a simple config file to adopt
  56      the make process to your target system.
  57
  58      Compiler Flags:
  59
  60      USE_SNMPTRAPD
  61         Use the netsnmp standard utility snmptrapd as trap-sink daemon.
  62         See * Trap-sink Daemon below for details.
  63
  64   3. Configure the make environment
  65
  66      The file config adopts the make environment automatically to suit your
  67      platform.
  68
  69   4. Compile the package
  70
  71      Type
  72         make or make LV=5.3 or make LV=5.1
  73
  74      If make succeeds you get for Linux/MacOS (Windows):
  75
  76      * a Lua extension library "snmp.so.1.0" (core.dll) in the src sub-directory.
  77      * a copy "core.so" (core.dll) of the same Lua extension library in ./snmp
  78
  79   5. Type
  80        make install or make LV=5.3 install or make LV=5.1 install
  81
  82      as user root in order to install all relevant
  83      files in standard places. The directory /usr/local is the default
  84      install prefix.
  85
  86
  87 * Installation via Luarocks
  88   -------------------------
  89   LuaSNMP can be installed via Luarocks.
  90
  91   Type
  92      sudo luarocks --lua-version=5.x install luasnmp LV=5.x
  93
  94
  95 * Trap-sink Daemon
  96   ----------------
  97   LuaSNMP supports the following trap-sink daemons:
  98
  99   snmptrapd
 100
 101      It is recommended to use this daemon, as it fully supports SNMP
 102      INFORM requests. Add the following line to your
 103      /etc/snmp/snmptrapd.conf file in order to get notified by
 104      snmptrapd:
 105
 106           traphandle default PATH-TO-LUA/lua \
 107                      PATH-TO-LUASNMP/trapd.lua [TRAPDPORT] [LOGFILE] [LOGLEVEL]
 108
 109      This instructs snmptrapd to execute the trapd.lua script, which will then
 110      in fact notify your luasnmp session about traps and informs using standard
 111      UDP datagrams on a user configurable port TRAPDPORT (6000 is used by default).
 112
 113      Note, that 'trapd.lua' is a normal Lua script, that requires it's environment
 114      correctly set, which typically happens by inheritance of the environment of the
 115      shell that starts snmptrapd. In particular 'trapd.lua' requires the following
 116      standard environment variables (examples):
 117
 118      For Lua 5.0:
 119      LUA_INIT=@/usr/local/share/lua/5.0/compat-5.1.lua
 120         Only required for Lua 5.0 as Lua 5.1 does not require compat-5.1.lua.
 121
 122      For Lua 5.1:
 123      LUA_INIT="require 'luarocks.require'"
 124         Let Lua find modules installed via luarocks.
 125
 126      LUA_PATH="./?.lua;./?/?.lua;/usr/local/share/lua/5.x/?.lua;/usr/local/share/lua/5.0/?/?.lua;/usr/local/share/lua/5.x/?/init.lua"
 127         Tell Lua where to find Lua modules (required). Note that luarocks path
 128         is not included here. With the corresponding setting of the LUA_INIT environment
 129         variable modules are first searched in the luarocks module repository and
 130         then inthe PATH given via LUA_PATH.
 131
 132      LUA_CPATH="./?.so;./l?.so;/usr/local/lib/lua/5.0/?.so;/usr/local/lib/lua/5.0/l?.so"
 133         Tell Lua where to find C modules (required). See LUA_PATH concerning module
 134         search order when luarocks is installed.
 135
 136      You may also want to write data from the last received trap into a logfile:
 137      just provide the full path of the logfile as second argument.
 138
 139      The third argument defines the level of logging used. See module LuaLogging
 140      for details.
 141
 142      Note, that you have to set the compiler switch USE_SNMPTRAPD when
 143      you compile the luasnmp package.
 144
 145
 146 * Trap log message format
 147   ---------------------
 148      In order to have the trapd.lua script work properly snmptrapfmt must be configured
 149      with the following format setting:
 150        SUBST=\#\ \
 151        NODEFMT=ip
 152        VARFMT="#[%s] %n (%t) : %v"
 153        LOGFMT="$x#$A#$e#$G#$S#$T$*"
 154      This ensure that the log message can be interpreted by the trapd script.
 155
 156 * Environment Variables
 157   ---------------------
 158
 159   The following environment variables are needed for using LuaSNMP:
 160
 161   LUASNMP_TRAPDPORT: Defines the port number to use on UDB socket between
 162                         snmptrapd and the trapd.lua script.
 163   LUASNMP_TRAPDPORT: Defines the port used by trapd.lua to capture events
 164                      from NET-SNMP's snmptrapd.
 165   LUASNMP_MIBDIRS:   Directory to find extra MIBs for LuaSNMP usage. Same functionality as
 166                      the MIBDIRS environment variable of NET-SNMP.
 167   MIBDIRS:           LuaSNMP searches in the path given by MIBDIRS for MIBs.
 168   SNMPCONFPATH:      LuaSNMP respects the standard NET-SNMP configuration path variable.
 169
 170
 171 * NetSNMP configuration files
 172   ---------------------------
 173
 174   NetSNMP uses a bunch of configuration files at various places. Here is a list of them
 175   with some personal notes.
 176
 177   /etc/snmp/snmpd.conf    Main agent configuration containing site specific agent definitions
 178                           that do not contain any secrete information.
 179                           (Note, that the temmplate file provided violates this recommendation,
 180                           simply remove the createUser directives)
 181                           template: etc/snmpd.conf
 182
 183   /var/lib/snmp/snmpd.conf        Automatic generated configuration entries, mainly encrypted user
 184                                   information
 185                                   template: none
 186
 187   /usr/share/snmp/snmpd.conf    User specific configuration: which user is allowed to work
 188                                 how on which part of the MIBtree (rwuser directive)
 189                                 template: etc/share_snmpd.conf
 190
 191   /etc/snmp/snmp.conf     Default User and Password. Eases SNMP3 commands.
 192                           template: etc/etc_snmp.conf
 193
 194   $(HOME)/.snmp/snmp.conf Defaults per user
 195                           template: etc/snmp.conf
 196
 197
 198 * SNMPv3 Considerations
 199   ---------------------
 200
 201   Generally, LuaSNMP has the same prerequisits as the NetSNMP library to get
 202   SNMP version 3 to work. Nevertheless, here are some useful hints to get the
 203   test script test.lua into operation for version 3.
 204
 205   1. Copy the template configuration files:
 206      etc/snmpd.conf             to     /etc/snmpd.conf
 207      etc/snmptrapd.conf         to     /etc/snmptrapd.conf
 208        You should adopt/select the line configuring the trapd.lua script execution
 209        to use the correct path to the Lua executable
 210      etc/snmp.conf              to     $(HOME)/.snmp/snmp.conf
 211
 212   2. Stop the SNMP daemon.
 213
 214   3. Create SNMP v3 users using the net-snmp-config command as follows:
 215             net-snmp-config --create-snmpv3-user -a "leuwer2006" leuwer
 216             net-snmp-config --create-snmpv3-user -a "ronja2006" ronja
 217      (The users shown are those used in test.lua.)
 218
 219      This adds createUser directives to /var/lib/snmpd.conf which are replaced
 220      by encrypted keys during snmpd startup.
 221
 222      If the way via net-snmp-config tool is missing or fails do it by hand and
 223      add the following into /var/lib/snmp/snmpd.conf
 224
 225      createUser leuwer MD5 leuwer2006 DES leuwer2006
 226      createUser ronja  MD5 ronja2006 DES ronja2006
 227
 228      You may choose SHA instead of MD5 and AES or AES128 instead of DES.
 229
 230   4. Create a file /usr/share/snmp/snmpd.conf and add the following lines
 231      rwuser leuwer
 232      rwuser ronja
 233      Note that the template named in 1) already contains these lines.
 234
 235   5. Start the SNMP daemon
 236
 237 * LuaSNMP on MS Windows
 238   ---------------------
 239
 240   - Compilation
 241         LuaSNMP does not compile against the development files that come with
 242         the net-snmp installer package. It compiles without problems
 243         against the configured and installed net-snmp 5.3.0.1 source package.
 244
 245   - Agents
 246         The provided test script test.lua works fine against the net-snmp agent
 247         snmpd built under cygwin.
 248         Read requests work fine against Microsoft's SNMP agent. I have taken no
 249         effort so far to configure the agent for write-access as well.
 250
 251   - Trap Forwarding
 252         Forwarding using the traphandle directive works fine for SNMP version 1,
 253         version 2c and version 3.
 254
 255   - MIB Loading
 256     Neither snmpd nor the applications load default libs without setting the
 257     MIBDIRS environment variable. At least this is what I observed in my net-snmp
 258     installation und Cygwin.
 259     Workaround: Set MIBDIRS in your .bashrc file, e.g.:
 260         export MIBDIRS=/usr/local/share/snmp/mibs
 261
 262   - The distribution comes with a shell script etc/snmpdwin32.sh which automatically
 263     installs / starts / stops /removes the daemons as Windows services. It also
 264     cares for the correct environment in order to use Lua as language for the
 265     trap handle script. The script currently doesn't configure the services to start
 266     automatically during startup. Hence you will have to start them manually using
 267        snmpdwin32.sh start
 268
 269   - The script etc/snmpdstart provides an alternative to windows services. It starts
 270     the agent and the trap daemon as background processes.
 271
 272
 273 * Comments and bug reports
 274   ------------------------
 275
 276   Please send your comments and bug reports to the Lua mailing list.
 277
 278 April 2006 (Dec 2008, July 2009, March 2010, Jan 2016)
 279
 280 Have fun.
 281 herbert.leuwer@gmx.de
 282