NMS-19639: Deprecate SNMP Config Rest Service v1

core/web-assets/src/main/assets/js/apps/onms-requisitions/lib/scripts/services/Requisitions.js

@@ -48,10 +48,10 @@ const RequisitionNode  = require('../model/RequisitionNode');
   *
   * @description The RequisitionsService provides all the required methods to access ReST API for the OpenNMS requisitions.
   *
-  * It uses Angular's Cache service to store localy all the requisitions after retrieving them from the server the first time.
+  * It uses Angular's Cache service to store locally all the requisitions after retrieving them from the server the first time.
   * This helps in terms of performance and responsiveness of the UI. Only changes are pushed back to the server.
   *
-  * Conflicts may accour if someone else is changing the requisitions at the same time.
+  * Conflicts may occur if someone else is changing the requisitions at the same time.
   *
   * If the cache is not going to be used, the controllers are responsible for maintaining the state of the data.
   */
@@ -74,7 +74,7 @@ const RequisitionNode  = require('../model/RequisitionNode');
     requisitionsService.internal.foreignSourcesUrl = 'rest/foreignSources';
     requisitionsService.internal.foreignSourcesConfigUrl = 'rest/foreignSourcesConfig';
     requisitionsService.internal.monitoringLocationsUrl = 'rest/monitoringLocations';
-    requisitionsService.internal.snmpConfigUrl = 'rest/snmpConfig';
+    requisitionsService.internal.snmpConfigUrl = 'api/v2/snmp-config';
     requisitionsService.internal.errorHelp = ' Check the OpenNMS logs for more details, or try again later.';
 
     requisitionsService.internal.excludedRequisitionNames = ['selfmonitor', 'minions'];
@@ -1428,9 +1428,10 @@ const RequisitionNode  = require('../model/RequisitionNode');
     requisitionsService.updateSnmpCommunity = function(ipAddress, snmpCommunity, snmpVersion) {
       const deferred = $q.defer();
 
-      const url = requisitionsService.internal.snmpConfigUrl + '/' + ipAddress;
+      const url = requisitionsService.internal.snmpConfigUrl + '/definition';
+
       $log.debug('updateSnmpCommunity: updating snmp community for ' + ipAddress);
-      $http.put(url, {'readCommunity' : snmpCommunity, 'version' : snmpVersion})
+      $http.put(url, {'readCommunity': snmpCommunity, 'version': snmpVersion, 'specific': [ipAddress] })
       .then(function updateSnmpCommunitySuccess() {
         $log.debug('updateSnmpCommunity: updated snmp community for ' + ipAddress);
         deferred.resolve(ipAddress);

core/web-assets/src/test/javascript/ng-requisitions/services/Requisitions.test.js

@@ -1002,8 +1002,8 @@ test('Service: RequisitionsService: deleteForeignSourceDefinition', function() {
 test('Service: RequisitionsService: updateSnmpCommunity', function() {
   console.log('Running tests for updateSnmpCommunity');
 
-  var url = requisitionsService.internal.snmpConfigUrl + '/192.168.1.1';
-  $httpBackend.expect('PUT', url, {'readCommunity' : 'my_community', 'version' : 'v2c'}).respond();
+  var url = requisitionsService.internal.snmpConfigUrl + '/definition';
+  $httpBackend.expect('PUT', url, {'readCommunity': 'my_community', 'version': 'v2c', 'specific': ['192.168.1.1']}).respond();
 
   return runDigest(requisitionsService.updateSnmpCommunity('192.168.1.1', 'my_community', 'v2c')).then(function(ip) {
     return expect(ip).toBe('192.168.1.1');
@@ -1044,10 +1044,12 @@ test('Service: RequisitionsService: quickAddNode', function() {
   quickNode.snmpCommunity = 'my_community';
   var node = quickNode.createRequisitionedNode().getOnmsRequisitionNode();
 
-  var updateSnmpUrl = requisitionsService.internal.snmpConfigUrl + '/' + quickNode.ipAddress;
-  $httpBackend.expect('PUT', updateSnmpUrl, {'readCommunity' : quickNode.snmpCommunity, 'version' : quickNode.snmpVersion}).respond();
+  var updateSnmpUrl = requisitionsService.internal.snmpConfigUrl + '/definition';
+  $httpBackend.expect('PUT', updateSnmpUrl, {'readCommunity' : quickNode.snmpCommunity, 'version' : quickNode.snmpVersion, 'specific': [quickNode.ipAddress]}).respond();
+
   var saveUrl = requisitionsService.internal.requisitionsUrl + '/' + quickNode.foreignSource + '/nodes';
   $httpBackend.expect('POST', saveUrl, node).respond({});
+
   var importUrl = requisitionsService.internal.requisitionsUrl + '/' + quickNode.foreignSource + '/import?rescanExisting=false';
   $httpBackend.expect('PUT', importUrl).respond({});
 

docs/modules/development/pages/rest/snmp_configuration_legacy.adoc

@@ -1,9 +1,9 @@
 
-= SNMP Configuration (Legacy)
+= SNMP Configuration (Legacy / Deprecated API)
 
 NOTE: {page-component-title} has been updated to move SNMP Configuration into the database.
-Please see xref:development:rest/snmp_configuration.adoc[SNMP Configuration] for the new REST API.
-Generally speaking you should avoid this API and use the new API instead, but if you have a use case that requires the legacy API, this page describes how to use it.
+Please see xref:development:rest/snmp_configuration.adoc[SNMP Configuration] for the new REST API (`api/v2/snmp-config`).
+The legacy API (`rest/snmpConfig`) has been deprecated and will be removed in a future release, and generally speaking you should avoid it and use the new API instead, but if you have a use case that requires the legacy API, this page describes how to use it.
 
 Use this interface to edit the community string, SNMP version, etc. for an IP address.
 If you make a change that would overlap with an existing `snmp-config.xml`, it will automatically create groups of `<definition />` entries as necessary.

docs/modules/operation/pages/deep-dive/provisioning/integration.adoc

@@ -56,15 +56,32 @@ curl -v -u admin:admin -X POST -H 'Content-type: application/xml' -d '@customer-
 
 === Step 2 - Update the SNMP configuration
 
-The xref:development:rest/snmp_configuration.adoc[snmpConfig endpoint] only supports a PUT request because it is an implied "update" of the configuration since it requires an IP address, and all IPs have a default configuration.
-This request is is passed to the SNMP configuration factory in {page-component-title} for optimization of the configuration store `snmp-config.xml`.
-This example changes the community string for the IP address 10.1.1.1 to `yRuSonoZ`.
+Update the community string or other data for this IP address.
 
-NOTE: Community string is the only required element.
+See the xref:development:rest/snmp_configuration.adoc[SNMP Configuration documentation] for more information.
 
-[source, console]
+This example changes the read community string for the IP address 10.1.1.1 to `yRuSonoZ`.
+
+NOTE: `readCommunity` is the only required element, other than `specific`.
+See the SNMP documentation for a full list of available elements and their descriptions.
+
+.Example: Update the SNMP Community string via curl (one-liner)
+[source, bash, console]
+----
+curl -v -u admin:admin -X PUT -H "Content-Type: application/json" -d '{ "readCommunity": "yRuSonoZ", "specific": ["10.1.1.1"] }' http://localhost:8980/opennms/api/v2/snmp-config/definition
+----
+
+.Example: Update the SNMP Community string via curl (formatted)
+[source, bash, console]
 ----
-curl -v -u admin:admin -X PUT -H "Content-Type: application/xml" -H "Accept: application/xml" -d "<snmp-info><community>yRuSonoZ</community><port>161</port><retries>1</retries><timeout>2000</timeout><version>v2c</version></snmp-info>" http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1
+curl -v -u admin:admin -X PUT \
+   -H "Content-Type: application/json" \
+   -d \
+'{
+  "readCommunity": "yRuSonoZ",
+  "specific": ["10.1.1.1"]
+}' \
+ 'http://localhost:8980/opennms/api/v2/snmp-config/definition'
 ----
 
 === Step 3 - Create/Update the Requisition

opennms-config/src/main/java/org/opennms/netmgt/config/SnmpConfigAccessService.java

@@ -34,6 +34,11 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * @deprecated This class is deprecated and will be removed in a future release. This is used by the v1 SNMP Rest API,
+ * which is being replaced by the new v2 SNMP Rest API.
+ */
+@Deprecated(forRemoval = true)
 public class SnmpConfigAccessService {
     private static final Logger LOG = LoggerFactory.getLogger(SnmpConfigAccessService.class);
 

opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/SnmpConfigRestService.java

@@ -87,7 +87,9 @@
  * <pre>
  * curl -v -X GET -u admin:admin http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1
  * </pre>
- * 
+ *
+ * @deprecated This v1 SNMP Config Rest API is deprecated as it is being replaced by the new v2 Rest API.
+ * It will be removed in a future release.
  * @author <a href="mailto:brozow@opennms.org">Mathew Brozowski</a>
  * @version $Id: $
  * @since 1.8.1
@@ -96,6 +98,7 @@
 @Path("snmpConfig")
 @Tag(name = "SnmpConfig", description = "SNMP Config API")
 @Transactional
+@Deprecated(forRemoval = true)
 public class SnmpConfigRestService extends OnmsRestService {
 
     @Autowired

opennms-webapp-rest/src/test/java/org/opennms/web/rest/v1/SnmpConfigRestServiceIT.java

@@ -49,6 +49,9 @@
 /**
  * TODO
  * 1. Need to figure it out how to create a Mock for EventProxy to validate events sent by RESTful service
+ *
+ * @deprecated This class is deprecated and will be removed in a future release.
+ * This is used by the v1 SNMP Rest API, which is being replaced by the new v2 SNMP Rest API.
  */
 @RunWith(OpenNMSJUnit4ClassRunner.class)
 @WebAppConfiguration
@@ -68,6 +71,7 @@
 })
 @JUnitConfigurationEnvironment(systemProperties = "org.opennms.timeseries.strategy=integration")
 @JUnitTemporaryDatabase
+// TODO: Remove when v1 SNMP API is removed (Horizon 37)
 public class SnmpConfigRestServiceIT extends AbstractSpringJerseyRestTestCase {
 
 	private static final int DEFAULT_PORT = 9161;

opennms-webapp/src/main/webapp/WEB-INF/applicationContext-spring-security.xml

@@ -69,7 +69,11 @@
     <intercept-url pattern="/rest/foreignSources/**" access="ROLE_PROVISION,ROLE_REST,ROLE_ADMIN"/>
     <intercept-url pattern="/rest/requisitions/**" access="ROLE_PROVISION,ROLE_REST,ROLE_ADMIN"/>
 
-    <!-- SNMP config is _only_ allowed for the provision or admin roles -->
+    <!--
+      SNMP config is _only_ allowed for the provision or admin roles.
+      Note that this v1 SNMP Config Rest API has been deprecated in favor of the v2 API under /api/v2/snmp-config
+      and will be removed in a future release.
+    -->
     <intercept-url pattern="/rest/snmpConfig/**" access="ROLE_PROVISION,ROLE_ADMIN"/>
 
     <!-- Allow users to POST to the Measurements API, which is read-only -->