Agent++Win32 API README =================================== Copyright (C) 2003-2010, Frank Fock +-------------------------------------+ | AgentX++Win32Master | +--------------------------------+----+ | AgentX++ | | +--------------------------------+ | | AGENT++ | | +---------+----------------------+ | | SNMP++ | AGENT++Win32SubAgent | | +---------+----------------------+ | | SNMPAPI | +-------------------------------------+ The AGENT++Win32SubAgent API provides an adapter implementation to the extended MicrosoftTM SNMP Extension API as supported by Windows 2000, XP, and CE. The API has been developed for VC++.NET (7.0). The AgentX++Win32Master API provides AgentX, AGENT++ and the extended MicrosoftTM SNMP Extension API in a single master agent. Both APIs are bundled together in the AGENT++Win32 API. Although the AGENT++Win32SubAgent API does not depend on AgentX++, it is though a subagent API and must be licensed for commercial use. The AGENT++Win32 API is licensed as part of AgentX++. See the AgentX++ license agreement at http://www.agentpp.com/agentX++/license.txt for more details. INSTALLATION ------------ Unzip the agent++win32.zip file into the same directory where you have unpacked SNMP++ and AGENT++: -+ +-snmp++ +-agent++ +-agent++win32 +-subagent_win32 +-agentx_pp_master +-examples +-agentx_master +-ATMExample COMPILATION =========== The subagent and the master API libs have to be compiled into different DLL/LIB files. AGENT++Win32SubAgent -------------------- SNMP++ and AGENT++ have to be compiled with the following preprocessor flags set: _NO_THREADS _NO_SNMPv3 Although, you may also compile the packages with _SNMPv3 enabled, disabling it will generate smaller DLLs. Modify your PATH environment variable to include the directories where the snmp_pp.dll, agent_pp.dll, and subagent_win32.dll have been created. To test your extension agent, you will have to copy those DLLs and the DLL of your subagent to \WINNT\System32. AGENT++Win32Master ------------------ Use the MSVC project file staticLIB.sln to compile the example AgentX++Win32 master agent. This will create a agentx++win32master.exe file in either the \msvc\static\debug or \msvc\static\release depending on the which configuration you choose. To replace your native WinXP/2000/NT4 agent: 1. Stop the SNMP service. 2. Backup the existing agent "snmp.exe" from the "C:\Windows\system32" by renaming it to, for example, "snmp.exe.orig". 3. Copy the "agentx++win32master.exe" to "C:\Windows\system32" and rename it to "snmp.exe". 4. Start the SNMP service again. That's all. If you have problems replacing the orignal file because it is recreated by the operating system, you can start Windows in safe mode and replace it then. Alternatively, the AgentX++Win32 master agent service can be installed and run parallel to the original SNMP service: 1. Copy the "agentx++win32master.exe" to "C:\Windows\system32". 2. On the command line change the current directory to "C:\Windows\system32". 3. Run "agentx++win32master.exe -i AgentXPPMaster" to install the service. 4. In the service panel of the OS, edit the parameters for the service to "-n AgentXPPMaster-p " where is a UDP port number other than 161, which the original SNMP service will continue to use (if not stopped). 5. Start the service. To uninstall the AgentXPPMaster service: 1. In the service panel of the OS, stop the AgentXPPMaster service. 2. When stopped, run "agentx++win32master.exe -u AgentXPPMaster" from the system32 directory. 3. The service will be removed after the next reboot. To get a full description of the command line options of the agentx++win32master.exe, run it with the "-?" option. To setup a persistent configuration directory and configure SNMPv3 initial passphrases, you will have to edit the registry. You can do so by starting the "C:\Windows\system32\regedt32.exe" application. The following subtree structure should be created (see also file agentx++win32master.reg that can be directly imported): [HKEY_LOCAL_MACHINE\SOFTWARE\Agentpp] [HKEY_LOCAL_MACHINE\SOFTWARE\Agentpp\AgentConfig] [HKEY_LOCAL_MACHINE\SOFTWARE\Agentpp\AgentConfig\ConfigPath] "1"="C:%HOMEPATH%\\AGENTPP\\CONFIG\\" [HKEY_LOCAL_MACHINE\SOFTWARE\Agentpp\AgentConfig\SNMPv3\USM] [HKEY_LOCAL_MACHINE\SOFTWARE\Agentpp\AgentConfig\SNMPv3\USM\InitialPassphrase] "auth"="initialPP" "priv"="initialPP" Replace "initialPP" by your passphrase and the ConfigPath value to an empty(!) directory of your choice. After you have restarted the SNMP service you should change the initial passphrases of the agent by accessing the agent via SNMPv3 and performing cloning of the initial users. Initially the agent can be accessed by using the following security names (without quotes): 1. "MD5" MD5 authentication using the "auth" initial passphrase, security level authNoPriv. 2. "SHA" SHA authentication using the "auth" initial passphrase, security level authNoPriv. 3. "MD5DES" Like "MD5" and additonally DES privacy using the "priv" passphrase. 4. "SHADES" Like "SHA" and additonally DES privacy using the "priv" passphrase. After you have cloned all necessary SNMPv3 users, you may clear the "auth" and "priv" values under the "InitialPassphrase" key. Make sure that you have configured a directory for your persistent configuration data. These will also hold information of the newly created SNMPv3 users. Then you can stop/restart the SNMP service and the initial users will no longer be available and the cloned users will provide access to the agent. If you have problems accessing the agent using SNMPv1/v2c, then you should check the "permitted agents" settings for the SNMP service. Please make sure that at least the host from which you tried to access the agent is listed in the permitted agents list. INSTALLING Extension Agents =========================== [Taken from Joseph C. Hu's README for AGENT++NT2.13 (joseph@trithian.com)] Warning: Be *VERY* *VERY* careful when you modify your Registry!!! Suppose that you have finished building the example Agents that came with the AGENT++ source code and you want to install them on your own NT machine and test them. I assume that you unzipped the Win32AGENT++ source code into C:\snmp so the example Agent is built as: C:\snmp\agent++_win32\examples\ATMExample\Debug\ATMExample.dll The first thing to do is to add registry entries for them under HKEY_LOCAL_MACHINE\SOFTWARE. By convention, you will create your own branch with your company's name under SOFTWARE. For illustration purpose, I assume this company is named Agent++. Under this branch, you should create SNMP\ExtensionAgents and create branches for each extension agents. Under each of these branches, you should create a branch called CurrentVersion. What you should now have are the branches: HKEY_LOCAL_MACHINE\SOFTWARE\AGENT++\SNMP\ExtensionAgents\ATMExample\CurrentVersion Under each of these branches, you should have a string value named "Pathname" and its value should be set to the absolute path to that DLL: HKEY_LOCAL_MACHINE\SOFTWARE\Agent++\SNMP\ExtensionAgents\atm_mib\CurrentVersion (Pathname = "C:\snmp\agent++_win32\examples\ATMExample\Debug\ATMExample.dll") With these branches entered, you can now modify the branch HKEY_LOCAL_MACHINE\SSYTEM\CurrentControlSet\Services\SNMP\Parameters\ExtensionAgents and add three string values to it: (ATMExample = "SOFTWARE\Agent++\SNMP\ExtensionAgents\atm_mib\CurrentVersion") Notice that these values are simply the branches you have previously created (with HKEY_LOCAL_MACHINE stripped.) The NT Extensible Agent really does not care what names you gave to these values. You could have entered: (1 = "SOFTWARE\AGENT++\SNMP\ExtensionAgents\ATMExample\CurrentVersion") and it would still have worked. After you have modified the registry, you should go to "Control Panel"/"services" and restart the SNMP service.