docs/sections/services/snmptrap/configuration.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Configuration
   5 =============
   6
   7 **trapd** configuration is controlled via a single JSON 'transaction'.
   8 This transaction can be:
   9
  10 - a reply from Config Binding Services
  11 - a locally hosted JSON file
  12
  13 The format of this message is described in the SNMPTRAP package, under:
  14
  15 .. code-block:: bash
  16
  17     <base install dir>/spec/snmptrap-collector-component-spec.json
  18
  19 There will also be a template JSON file with example/default values found at:
  20
  21 .. code-block:: bash
  22
  23     <base install dir>/etc/snmptrapd.json
  24
  25 If you are going to use a local file, the env variable below must be defined before SNMPTRAP runs.  There is a default value set in the SNMPTRAP startup script (bin/snmptrapd.sh):
  26
  27 .. code-block:: bash
  28
  29     export CBS_SIM_JSON=../etc/snmptrapd.json
  30
  31 In either scenario, the format of the config message/transaction *is the same*.  An example is described below.
  32
  33 JSON CONFIGURATION EXPLAINED
  34 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  35
  36 Variables of interest (e.g. variables that should be inspected/modified for a specific runtime environment) are listed below for convenience.  The entire file is provided later in this page for reference.
  37
  38 Potential Config Changes in your environment
  39 """"""""""""""""""""""""""""""""""""""""""""
  40
  41 .. code-block:: bash
  42
  43     in protocols section:
  44
  45        "ipv4_interface": "0.0.0.0",    # IPv4 address of interface to listen on - "0.0.0.0" == "all"
  46        "ipv4_port": 6162,              # UDP port to listen for IPv4 traps on (6162 used in docker environments when forwarding has been enabled)
  47        "ipv6_interface": "::1",        # IPv6 address of interface to listen on - "::1" == "all"
  48        "ipv6_port": 6162               # UDP port to listen for IPv6 traps on (6162 used in docker environments when forwarding has been enabled)
  49
  50     in cache section:
  51
  52        "dns_cache_ttl_seconds": 60     # number of seconds trapd will cache IP-to-DNS-name values before checking for update
  53
  54     in files section:
  55
  56        "minimum_severity_to_log": 2    # minimum message level to log; 0 recommended for debugging, 3+ recommended for runtime/production
  57
  58     in snmpv3_config section:
  59
  60        (see detailed snmpv3_config discussion below)
  61
  62 snmpv3_config
  63 """""""""""""
  64
  65 SNMPv3 added significant authorization and privacy capabilities to the SNMP standard.  As it relates to traps, this means providing the proper privacy, authorization, engine and user criteria for each agent that would like to send traps to a particular trapd instance.
  66
  67 This is done by adding blocks of valid configuration data to the "snmpv3_config" section of the JSON config/transaction.  These blocks are recurring sets of:
  68
  69 .. code-block:: json
  70
  71     {
  72     "user": "<userId>",
  73     "engineId": "<engineId>",
  74     "<authProtocol>": "<authorizationKeyValue>",
  75     "<privProtocol>": "<privacyKeyValue>"
  76     }
  77
  78 Valid values for authProtocol in JSON configuration:
  79
  80 .. code-block:: bash
  81
  82     usmHMACMD5AuthProtocol
  83     usmHMACSHAAuthProtocol
  84     usmHMAC128SHA224AuthProtocol
  85     usmHMAC192SHA256AuthProtocol
  86     usmHMAC256SHA384AuthProtocol
  87     usmHMAC384SHA512AuthProtocol
  88     usmNoAuthProtocol
  89
  90 Valid values for privProtocol in JSON configuration:
  91
  92 .. code-block:: bash
  93
  94     usm3DESEDEPrivProtocol
  95     usmAesCfb128Protocol
  96     usmAesCfb192Protocol
  97     usmAesBlumenthalCfb192Protocol
  98     usmAesCfb256Protocol
  99     usmAesBlumenthalCfb256Protocol
 100     usmDESPrivProtocol
 101     usmNoPrivProtocol
 102
 103 User and engineId values are left up to the administrator, and must conform to SNMPv3 specifications as explained at `https://tools.ietf.org/html/rfc3414` .
 104
 105
 106 Sample JSON configuration
 107 """""""""""""""""""""""""
 108
 109 The format of the JSON configuration that drives all behavior of SNMPTRAP is probably best described using an example:
 110
 111 .. code-block:: json
 112
 113     {
 114         "snmptrapd": {
 115             "version": "1.4.0",
 116             "title": "ONAP SNMP Trap Receiver"
 117         },
 118         "protocols": {
 119             "transport": "udp",
 120             "ipv4_interface": "0.0.0.0",
 121             "ipv4_port": 6162,
 122             "ipv6_interface": "::1",
 123             "ipv6_port": 6162
 124
 125         },
 126         "cache": {
 127             "dns_cache_ttl_seconds": 60
 128         },
 129         "publisher": {
 130             "http_timeout_milliseconds": 1500,
 131             "http_retries": 3,
 132             "http_milliseconds_between_retries": 750,
 133             "http_primary_publisher": "true",
 134             "http_peer_publisher": "unavailable",
 135             "max_traps_between_publishes": 10,
 136             "max_milliseconds_between_publishes": 10000
 137         },
 138         "streams_publishes": {
 139             "sec_fault_unsecure": {
 140                 "type": "message_router",
 141                 "aaf_password": null,
 142                 "dmaap_info": {
 143                     "location": "mtl5",
 144                     "client_id": null,
 145                     "client_role": null,
 146                     "topic_url": "http://localhost:3904/events/ONAP-COLLECTOR-SNMPTRAP"
 147                 },
 148                 "aaf_username": null
 149             }
 150         },
 151         "files": {
 152             "runtime_base_dir": "/opt/app/snmptrap",
 153             "log_dir": "logs",
 154             "data_dir": "data",
 155             "pid_dir": "tmp",
 156             "arriving_traps_log": "snmptrapd_arriving_traps.log",
 157             "snmptrapd_diag": "snmptrapd_prog_diag.log",
 158             "traps_stats_log": "snmptrapd_stats.csv",
 159             "perm_status_file": "snmptrapd_status.log",
 160             "eelf_base_dir": "/opt/app/snmptrap/logs",
 161             "eelf_error": "error.log",
 162             "eelf_debug": "debug.log",
 163             "eelf_audit": "audit.log",
 164             "eelf_metrics": "metrics.log",
 165             "roll_frequency": "hour",
 166             "minimum_severity_to_log": 3
 167         },
 168         "snmpv3_config": {
 169             "usm_users": [
 170                 {
 171                     "engineId": "8000000000000001",
 172                     "user": "user1",
 173                     "usmDESPrivProtocol": "privkey1",
 174                     "usmHMACMD5AuthProtocol": "authkey1"
 175                 },
 176                 {
 177                     "engineId": "8000000000000002",
 178                     "user": "user2",
 179                     "usm3DESEDEPrivProtocol": "privkey2",
 180                     "usmHMACMD5AuthProtocol": "authkey2"
 181                 },
 182                 {
 183                     "engineId": "8000000000000003",
 184                     "user": "user3",
 185                     "usmAesCfb128Protocol": "privkey3",
 186                     "usmHMACMD5AuthProtocol": "authkey3"
 187                 },
 188                 {
 189                     "engineId": "8000000000000004",
 190                     "user": "user4",
 191                     "usmAesBlumenthalCfb192Protocol": "privkey4",
 192                     "usmHMACMD5AuthProtocol": "authkey4"
 193                 },
 194                 {
 195                     "engineId": "8000000000000005",
 196                     "user": "user5",
 197                     "usmAesBlumenthalCfb256Protocol": "privkey5",
 198                     "usmHMACMD5AuthProtocol": "authkey5"
 199                 },
 200                 {
 201                     "engineId": "8000000000000006",
 202                     "user": "user6",
 203                     "usmAesCfb192Protocol": "privkey6",
 204                     "usmHMACMD5AuthProtocol": "authkey6"
 205                 },
 206                 {
 207                     "engineId": "8000000000000007",
 208                     "user": "user7",
 209                     "usmAesCfb256Protocol": "privkey7",
 210                     "usmHMACMD5AuthProtocol": "authkey7"
 211                 },
 212                 {
 213                     "engineId": "8000000000000009",
 214                     "user": "user9",
 215                     "usmDESPrivProtocol": "privkey9",
 216                     "usmHMACSHAAuthProtocol": "authkey9"
 217                 },
 218                 {
 219                     "engineId": "8000000000000010",
 220                     "user": "user10",
 221                     "usm3DESEDEPrivProtocol": "privkey10",
 222                     "usmHMACSHAAuthProtocol": "authkey10"
 223                 },
 224                 {
 225                     "engineId": "8000000000000011",
 226                     "user": "user11",
 227                     "usmAesCfb128Protocol": "privkey11",
 228                     "usmHMACSHAAuthProtocol": "authkey11"
 229                 },
 230                 {
 231                     "engineId": "8000000000000012",
 232                     "user": "user12",
 233                     "usmAesBlumenthalCfb192Protocol": "privkey12",
 234                     "usmHMACSHAAuthProtocol": "authkey12"
 235                 },
 236                 {
 237                     "engineId": "8000000000000013",
 238                     "user": "user13",
 239                     "usmAesBlumenthalCfb256Protocol": "privkey13",
 240                     "usmHMACSHAAuthProtocol": "authkey13"
 241                 },
 242                 {
 243                     "engineId": "8000000000000014",
 244                     "user": "user14",
 245                     "usmAesCfb192Protocol": "privkey14",
 246                     "usmHMACSHAAuthProtocol": "authkey14"
 247                 },
 248                 {
 249                     "engineId": "8000000000000015",
 250                     "user": "user15",
 251                     "usmAesCfb256Protocol": "privkey15",
 252                     "usmHMACSHAAuthProtocol": "authkey15"
 253                 },
 254                 {
 255                     "engineId": "8000000000000017",
 256                     "user": "user17",
 257                     "usmDESPrivProtocol": "privkey17",
 258                     "usmHMAC128SHA224AuthProtocol": "authkey17"
 259                 },
 260                 {
 261                     "engineId": "8000000000000018",
 262                     "user": "user18",
 263                     "usm3DESEDEPrivProtocol": "privkey18",
 264                     "usmHMAC128SHA224AuthProtocol": "authkey18"
 265                 },
 266                 {
 267                     "engineId": "8000000000000019",
 268                     "user": "user19",
 269                     "usmAesCfb128Protocol": "privkey19",
 270                     "usmHMAC128SHA224AuthProtocol": "authkey19"
 271                 },
 272                 {
 273                     "engineId": "8000000000000020",
 274                     "user": "user20",
 275                     "usmAesBlumenthalCfb192Protocol": "privkey20",
 276                     "usmHMAC128SHA224AuthProtocol": "authkey20"
 277                 },
 278                 {
 279                     "engineId": "8000000000000021",
 280                     "user": "user21",
 281                     "usmAesBlumenthalCfb256Protocol": "privkey21",
 282                     "usmHMAC128SHA224AuthProtocol": "authkey21"
 283                 },
 284                 {
 285                     "engineId": "8000000000000022",
 286                     "user": "user22",
 287                     "usmAesCfb192Protocol": "privkey22",
 288                     "usmHMAC128SHA224AuthProtocol": "authkey22"
 289                 },
 290                 {
 291                     "engineId": "8000000000000023",
 292                     "user": "user23",
 293                     "usmAesCfb256Protocol": "privkey23",
 294                     "usmHMAC128SHA224AuthProtocol": "authkey23"
 295                 },
 296                 {
 297                     "engineId": "8000000000000025",
 298                     "user": "user25",
 299                     "usmDESPrivProtocol": "privkey25",
 300                     "usmHMAC192SHA256AuthProtocol": "authkey25"
 301                 },
 302                 {
 303                     "engineId": "8000000000000026",
 304                     "user": "user26",
 305                     "usm3DESEDEPrivProtocol": "privkey26",
 306                     "usmHMAC192SHA256AuthProtocol": "authkey26"
 307                 },
 308                 {
 309                     "engineId": "8000000000000027",
 310                     "user": "user27",
 311                     "usmAesCfb128Protocol": "privkey27",
 312                     "usmHMAC192SHA256AuthProtocol": "authkey27"
 313                 },
 314                 {
 315                     "engineId": "8000000000000028",
 316                     "user": "user28",
 317                     "usmAesBlumenthalCfb192Protocol": "privkey28",
 318                     "usmHMAC192SHA256AuthProtocol": "authkey28"
 319                 },
 320                 {
 321                     "engineId": "8000000000000029",
 322                     "user": "user29",
 323                     "usmAesBlumenthalCfb256Protocol": "privkey29",
 324                     "usmHMAC192SHA256AuthProtocol": "authkey29"
 325                 },
 326                 {
 327                     "engineId": "8000000000000030",
 328                     "user": "user30",
 329                     "usmAesCfb192Protocol": "privkey30",
 330                     "usmHMAC192SHA256AuthProtocol": "authkey30"
 331                 },
 332                 {
 333                     "engineId": "8000000000000031",
 334                     "user": "user31",
 335                     "usmAesCfb256Protocol": "privkey31",
 336                     "usmHMAC192SHA256AuthProtocol": "authkey31"
 337                 },
 338                 {
 339                     "engineId": "8000000000000033",
 340                     "user": "user33",
 341                     "usmDESPrivProtocol": "privkey33",
 342                     "usmHMAC256SHA384AuthProtocol": "authkey33"
 343                 },
 344                 {
 345                     "engineId": "8000000000000034",
 346                     "user": "user34",
 347                     "usm3DESEDEPrivProtocol": "privkey34",
 348                     "usmHMAC256SHA384AuthProtocol": "authkey34"
 349                 },
 350                 {
 351                     "engineId": "8000000000000035",
 352                     "user": "user35",
 353                     "usmAesCfb128Protocol": "privkey35",
 354                     "usmHMAC256SHA384AuthProtocol": "authkey35"
 355                 },
 356                 {
 357                     "engineId": "8000000000000036",
 358                     "user": "user36",
 359                     "usmAesBlumenthalCfb192Protocol": "privkey36",
 360                     "usmHMAC256SHA384AuthProtocol": "authkey36"
 361                 },
 362                 {
 363                     "engineId": "8000000000000037",
 364                     "user": "user37",
 365                     "usmAesBlumenthalCfb256Protocol": "privkey37",
 366                     "usmHMAC256SHA384AuthProtocol": "authkey37"
 367                 },
 368                 {
 369                     "engineId": "8000000000000038",
 370                     "user": "user38",
 371                     "usmAesCfb192Protocol": "privkey38",
 372                     "usmHMAC256SHA384AuthProtocol": "authkey38"
 373                 },
 374                 {
 375                     "engineId": "8000000000000039",
 376                     "user": "user39",
 377                     "usmAesCfb256Protocol": "privkey39",
 378                     "usmHMAC256SHA384AuthProtocol": "authkey39"
 379                 },
 380                 {
 381                     "engineId": "8000000000000041",
 382                     "user": "user41",
 383                     "usmDESPrivProtocol": "privkey41",
 384                     "usmHMAC384SHA512AuthProtocol": "authkey41"
 385                 },
 386                 {
 387                     "engineId": "8000000000000042",
 388                     "user": "user42",
 389                     "usm3DESEDEPrivProtocol": "privkey42",
 390                     "usmHMAC384SHA512AuthProtocol": "authkey42"
 391                 },
 392                 {
 393                     "engineId": "8000000000000043",
 394                     "user": "user43",
 395                     "usmAesCfb128Protocol": "privkey43",
 396                     "usmHMAC384SHA512AuthProtocol": "authkey43"
 397                 },
 398                 {
 399                     "engineId": "8000000000000044",
 400                     "user": "user44",
 401                     "usmAesBlumenthalCfb192Protocol": "privkey44",
 402                     "usmHMAC384SHA512AuthProtocol": "authkey44"
 403                 },
 404                 {
 405                     "engineId": "8000000000000045",
 406                     "user": "user45",
 407                     "usmAesBlumenthalCfb256Protocol": "privkey45",
 408                     "usmHMAC384SHA512AuthProtocol": "authkey45"
 409                 },
 410                 {
 411                     "engineId": "8000000000000046",
 412                     "user": "user46",
 413                     "usmAesCfb192Protocol": "privkey46",
 414                     "usmHMAC384SHA512AuthProtocol": "authkey46"
 415                 },
 416                 {
 417                     "engineId": "8000000000000047",
 418                     "user": "user47",
 419                     "usmAesCfb256Protocol": "privkey47",
 420                     "usmHMAC384SHA512AuthProtocol": "authkey47"
 421                 }
 422
 423        }