dnscrypto-proxy: Update to release 1.3.0
[tomato.git] / release / src / router / snmp / README.win32
blob0313e5981a0acdbc0d60b72e0da24ef52c623cbe
1 ***************************************************************************
3 * README.win32
5 ***************************************************************************
7 This guide describes building with Microsoft C++ and with
8 the gcc compiler from Cygwin.  As developers build with
9 other Win32 environments, their notes will be included here.
12 The remainder of this guide has the following sections :
14 Status as of 18-Sep-2002 for Win32 platforms
15 Status as of 5-Nov-2001 for Win32 platforms
16 Installing Platform SDK
17 Building with MS VC++
18 Building with OpenSSL with MS VC++
19 Installing from MS VC++ build
20 Building with Cygwin
21 Extending the Agent with MS VC++
22 Notes on SET support for WIN32 ports
23 Acknowledgements
26 ***************************************************************************
28 * Status as of 18-Sep-2002 for Win32 platforms
30 ***************************************************************************
32   -  new project files created for those wishing to use the platform sdk
33      for more functionality. The default workspace, win32.dsw, does not
34      require the platform sdk. Uses who have installed the platform sdk
35      can use win32sdk.dsw for additional functionality.
36   -  For some as-yet unknown reason, the file descriptors created for the
37      internal callback transport are causing problems with select(), so
38      internal callbacks have been disabled until a fix can be found.
39      This almost certainly means that AgentX will no longer work for win32.
40   -  There appears to be a problem with the libsnmp_dll project, so build
41      the regular libsnmp instead. This, of course, means that the
42      applications will be a bit bigger, but at least they run.
44 WIN32 savy developers are strongly encouraged to lend a hand in helping
45 to fix these problems, as none of the core developers are very enthusiastic
46 about working on windows. We'll probably get around to fixing things
47 eventually, but if you can help, let us know.
50 ***************************************************************************
52 * Status as of 5-Nov-2001 for Win32 platforms
54 ***************************************************************************
56   -  the client applications work
57   -  the core framework of the agent works
58   -  the system, snmp, ip, tcp, udp, icmp mibgroups work
59           (assuming one installs the option Platform SDK)
60   -  the target, agentx, smux, notification groups compile
61   -  extending the agent to support enterprise-specific MIBs works
62   -  running the agent on a non-standard port works
63   -  running the UCD agent instead of the MS supplied one "works"
64           (at the loss of most of the functionality)
65   -  running the UCD agent as a "subagent" of the MS one does not work
66           (i.e. using the SNMP.dll interface)
67   -  running the UCD agent as a subagent of an AgentX master "works"
68           (bearing in mind this support is alpha-code)
70 All applications build with both MS VC++ and Cygwin.
72 Note: The agent cannot be built as an extensible SNMP agent that
73 will work with Microsoft's agent.
75 Neither snmpd nor snmptrapd register as NT services.
77 Snmptrapd does not "share" nor multiplex traps with SNMPTRAP.EXE,
78 a program that is available from Microsoft or ACE#COMM.
81 ***************************************************************************
83 * Installing Platform SDK
85 ***************************************************************************
87 The core elements of the mibII group of the agent, use the "IP Helper API"
88 which is part of Microsoft's "Core Platform SDK".  This is typically
89 not installed by default, but can be downloaded from
90                 http://msdn.microsoft.com/downloads/
91 as follows:
93     -  Using Internet Explorer (Netscape won't work), go to the above URL
94     -  From the menu at the left, select
95                 "Software Development Kits"
96                 "Platform SDK"
97     -  From the new window that appears, select "Core SDK".
98     -  The full Core SDK is ~240Mb (expanding to ~560Mb on installation).
99        In fact, the only portion that's required is the basic "Build
100        Environment" (36Mb) So it's safe to deselect the pre-release version,
101        documentation, sample code and 64-bit elements.
103     -  Once this package has installed, from the Start Menu run
104         "Register PSDK directories with Visual Studio"
107 To buld the agent, make sure you use the win32sdk.dsw workspace.
109 The full agent should now compile successfully.
112 ***************************************************************************
114 * Building with MS VC++
116 ***************************************************************************
118 The win32 directory contains a Microsoft VC++ (6.0) workspace and
119 project files to build both static and DLL versions of the UCD SNMP
120 library and the applications. Until recently it is known to build with
121 VC++ 5.0 too, unfortunately none of the developers have this version around
122 anymore.
124 Building with earlier compiler versions has not been attempted.  Success
125 stories are welcomed.
127 A manually generated config.h file has been provided for use with the
128 win32 build since the basic win32 environment does not support autoconf.
129 Note: the compiled in MIB path is \usr\mibs which may be changed by
130 editing win32/config.h.  Note that the install instructions below
131 should be adjusted when changes are made to paths.
133 To build the libraries and applications, open the workspace file
134 "win32\win32.dsw" from VC++.
136 Note there is a Debug version and Release version for each subproject.
137 Due to the way the libraries are organized, there are exactly two
138 library versions that work :
140   1) libsnmp Debug ;  and 2) libsnmp_dll Release
142 [Actaully, I'm not sure that is true anymore. I have had success with
143 both libsnmp Debug and Release, and no luch with libsnmp_dll.]
145 The projects are arranged so that ALL of the usable products,
146 the .lib, .dll, and .exe files, are written to the win32\bin
147 directory.  The win32\lib directory is used only to build the
148 the files in the win32\bin directory.  Once building is completed,
149 there is no further use for the files in the win32\lib directory.
151 The Debug product .exe files have "_d" appended to the basename
152 of the applications.  This is so the Debug and Release versions
153 of an application can be built and tested separately.
156 Runtime libraries
157 -----------------
159 Note that the library must be built using the same options as the
160 application which it will be linked with. In particular, the run-time
161 libraries must match (Project settings, C/C++ tab, 'Code Generation'
162 category).
164 For example, linking in an snmplib built to use the Multithreaded DLL
165 runtime library to an application configured for the Debug
166 Multithreaded DLL runtime library results in a link error along the
167 lines of 'defaultlib "MSVCRT" conflicts with use of other libs'.   If
168 you receive a similar message, check that the projects settings
169 between library and application match up.
171 Debug Information
172 -----------------
174 Note that VC++ 6.0 has new options for for debugging information -
175 the 'Program Database'.  This option is set in the Project settings,
176 C/C++ tab, 'General' category, and is turned on by default during the
177 conversion of the project files. This option is not for use with a
178 library, as it embeds debug information into the library that
179 references an external file that will not be available to the linking
180 application. If you get an error message along the lines of
181 'debugging information not available in file vc60.pdb, make sure the
182 library debug option is set to 'C7 compatible'.
184 To build the Release versions:
185 Click Build->Batch Build. Uncheck all Debug and libsnmp versions.
186 Make sure libsnmp_dll Release and all other Release versions
187 are checked.  Rebuild All.  If the library DLL link fails, add
188 missing function names to libsnmp_dll/libsnmp.def.
190 To build the Debug versions:
191 Click Build->Batch Build. Uncheck all Release and libsnmp_dll versions.
192 Make sure libsnmp Debug and all other Debug versions
193 are checked. Rebuild All.
195 To build both Debug and Release versions:
196 Click Build->Batch Build.  Check all versions.  Uncheck
197 "libsnmp Release" and "libsnmp_dll Debug" versions only.
198 Then click Release All.
201 ***************************************************************************
203 * Building with OpenSSL with MS VC++
205 ***************************************************************************
207 OpenSSL is required to support the encryption capabilities in SNMPv3
208 (and will also support MD5 authentication). The win32 version of OpenSSL
209 can be built from the source at:
211 ftp://ftp.openssl.org/source/
213 Follow the instructions for building on win32 in that package. if you do
214 not have the M$ assembler installed (MASM) you can get a free one(NASM)
215 from:
217 http://www.kernel.org/pub/software/devel/nasm
219 You will also need to change the win32/config.h file from
222 /* define if you are using the internal MD5 code */
223 #define USE_INTERNAL_MD5 1
227 /* define if you are using the internal MD5 code */
228 #undef USE_INTERNAL_MD5
230 /* define if you are using OpenSSL */
231 #define USE_OPENSSL 1
234 now you will need to edit the VC++ Project settings for the libraries
235 and applications. Change the Settings->Link->'Object/Library Modules' to
236 include
238 libeay32.lib
240 when installing be sure to place libeay32.dll on your search path (e.g.,
241 usr\bin)
244 ***************************************************************************
246 * Installing from MS VC++ build
248 ***************************************************************************
250 Create these subdirectories on the root directory of the
251 volume you wish to hold the UC-Davis SNMP applications :
253   usr, usr\bin, usr\mibs, usr\lib, usr\include\ucd-snmp
255 Copy mibs\*.txt to usr\mibs
256 Copy win32\bin\*.* to usr\bin
257 Copy win32\lib\*.* to usr\lib
258 Copy snmplib\*.h to usr\include\ucd-snmp
259 Copy win32\config.h to usr\include\ucd-snmp\ucd-snmp-config.h
261 if using OpenSSL
262 Copy libeay32.dll to usr\bin
263 Copy libeay32.lib to usr\lib
265 Installing is complete.  You may want to create a compressed
266 archive of the \usr hierarchy.
269 ***************************************************************************
271 * Building with Cygwin
273 ***************************************************************************
275 An alternate way to build UCD SNMP for win32 is to use Cygnus's cygwin32
276 environment.  Information on the Cygnus cygwin32 environment is available
277 on the web at: http://sources.redhat.com/cygwin/.
279 Cygwin allows you to compile almost the complete agent and applications.
280 The following configure options creates a working set of programs:
282 ./configure --with-mib-modules="host agentx smux examples/example" \
283         --with-out-mib-modules=host/hr_network \
284         --with-libs="-lregex -liphlpapi"
286 This has been tested for Windows 98 and Windows NT 4.0.  In order for
287 the process part of the host resources MIB to work under NT you will need
288 to get hold of the PSAPI.DLL. This available under the download section
289 of www.microsoft.com. The DLL is included with Windows 2000 and XP,
290 and is also part of the VC++ distribution.  The IPHLPAPI library is
291 part of the "Microsoft Platform SDK", which is also available from
292 www.microsoft.com.  See above for details.
295 ***************************************************************************
297 * Extending the Agent with MS VC++
299 ***************************************************************************
301 Assuming that the MIB compiler generated the my.h and my.c files for the
302 custom MIB "my", the following changes are required to extend the agent
303 using VC++:
305    - Add the my.h and my.c files to your 'netsnmpmibs' project in VC++.
306    - Next edit the '<sourcedir>\win32\mib_module_includes.h' file to
307      add an include to your .h file.
309         #include "mibgroup/my.h"
311    - Next edit the '<sourcedir>\win32\mib_module_inits.h' file to add
312      code to call your initialize function.
314         if (should_init("my")) init_my();
317 That's all that is needed. Now go ahead and compile the 'netsnmpmibs'
318 and 'snmpd' project. And things should work just fine.
321 ***************************************************************************
323 * Notes on SET support for WIN32 ports
325 ***************************************************************************
327 Requirements:
329   Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later. 
330   Windows 95/98/Me: Requires Windows 98 or later. 
331   Library: Use IPHLPAPI.LIB 
333 Note: IPHLPAPI.LIB is part of the "Microsoft Platform SDK", which may be
334       freely downloaded from www.microsoft.com.  See above for details.
336 Windows support for SET on following groups:
338 interfaces:
339 ----------
340 ifAdminStatus is read-write. Status can be set with either 'up' or
341 'down'. (IE, 'testing' status is not supported.)
344 ip group:
345 --------
346 Scalar objects: 
347 ipForwarding:Currently windows supports only ON->OFF (IE,
348 enable->disable). For any other value, it returns with failure.
350 ipDefaultTTL: Supports value greater than or equal to 0. 
352 Table objects:
353 -------------
354 1. ipRouteTable:
355    ------------
356 route_write.c implements this.
358 ipRouteDest: Setting this value, updates row with new ipRouteDest and all other
359              entries will be same as old row. 
360     EX:
361     Consider there is an entry with ipRouteDest = 10.0.0.20
362     Request, snmpset localhost private ip.ipRouteTable.ipRouteEntry.ipRouteDest.10.0.0.20 -a 10.0.0.16
363     Updates that row with ipRouteDest = 10.0.0.16
365 ipRouteIfIndex:Write supported.
367 ipRouteMetric1: Supports value greater than or equal to -1
369 ipRouteMetric2, ipRouteMetric3, ipRouteMetric4, ipRouteMetric5: Even though
370                 call returns with success, Windows doesn't change these (as
371                 these are not used in Windows)
373 ipRouteNextHop: Write supported.
375 ipRouteType: Write Supported. If value is 2, IE 'invalid', it deletes the entry.
377 ipRouteAge: Whenever any row is updated this will be automatically reset.
379 ipRouteMask: Write Supported.
381 Creation of ipRouteTable row:
382 -----------------------------
383 snmpset request for non existent OID with ipRouteIfIndex, ipRouteMetric1, 
384 ipRouteNextHop and ipRouteMask varbinds, creates a row.
386 snmpset with create option is not supported, as row creation requires 
387 ipRouteIfIndex, ipRouteMetric1, ipRouteNextHop and ipRouteMask  in a single 
388 request.
390 Example to create a row:
391 -----------------------
392 Consider there is no entry for 10.0.0.18
394 snmpset localhost private ip.ipRouteTable.ipRouteEntry.ipRouteIfIndex.10.0.0.18 i 2 4.21.1.ipRouteMask.10.0.0.18 a 255.255.255.255 4.21.1.ipRouteNextHop.10.0.0.0 a 10.0.0.0 4.21.1.ipRouteMetric1.10.0.0.18 i 1
396 If ipRouteIfIndex is valid then creates row with:
397 ipRouteIfIndex = 2
398 ipRouteMask = 255.255.255.255
399 ipRouteNextHop = 10.0.0.0
400 ipRouteMetric1 = 1
402 2. ipNetToMediaTable:
403 --------------------
404 ipNetToMediaIfIndex: write supported
405 ipNetToMediaPhysAddress: write supported
406 ipNetToMediaNetAddress: write supported
407 ipNetToMediaType: write supported, setting with value 2, deletes the row.
409 Creation of row:
410 --------------------
411 snmpset request for non existent OID with ipNetToMediaPhysAddress varbind
412 creates a row.
414 snmpset with create option is not supported, as row creation requires 
415 ipNetToMediaPhysAddress in a request 
416 request.
418 Example to create a row:
419 -----------------------
420 Consider there is no entry for 10.0.0.32
422 snmpset localhost private ip.ipNetToMediaTable.ipNetToMediaEntry.ipNetToMediaPhysAddress.2.10.0.0.32 x efcd12130103
424 If ipNetToMediaIfIndex is valid then creates row with:
425 ipNetToMediaIfIndex = 2
426 ipNetToMediaPhysAddress = ef:cd:12:12:01:03
427 ipNetToMediaNetAddress = 10.0.0.32
428 ipNetToMediaType = 4
430 TCP:
432 tcpConnState of tcpConnTable is writable and the only value which may
433 be set by a management station is deleteTCB(12)
437 ***************************************************************************
439 * Acknowledgements
441 ***************************************************************************
443 These people are known to have contributed to one or more of
444 the Win32 platform ports.  If you have, and your name is not here,
445 please accept our apologies, and tell us so we can add your name.
447 David Perkins, Joe Marzot, Wes Hardaker, Niels Baggesen, Dave Shield,
448 Robert Story, Suvrit Sra, Mike Slifcak.
450 A very special thank you goes to Latha Prabhu who contributed the complete
451 MIB-II support, including write support. This has put the Windows port
452 in the top support class for net-snmp.