#Net-SNMP

####Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with this module
   • What this module affects
   • What this module requires
   • [Beginning with this module](#beginning-with-this module)
   • Upgrading
4. Usage - Configuration options and additional functionality
   • Client
   • Trap Daemon
   • SNMPv3 Users
   • Access Control
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
   • OS Support
   • Notes
   • Issues
7. Development - Guide for contributing to the module

##Overview

This Puppet module manages the installation and configuration of Net-SNMP client, server, and trap server. It also can create a SNMPv3 user with authentication and privacy passwords.

##Module Description

Simple Network Management Protocol (SNMP) is a widely used protocol for monitoring the health and welfare of network and computer equipment. Net-SNMP implements SNMP v1, SNMP v2c, and SNMP v3 using both IPv4 and IPv6. This Puppet module manages the installation and configuration of the Net-SNMP client, server, and trap server. It also can create a SNMPv3 user with authentication and privacy passwords.

Only platforms that have Net-SNMP available are supported. This module will not work with AIX or Solaris SNMP.

##Setup

###What this module affects

• Installs the Net-SNMP client package and configuration.
• Installs the Net-SNMP daemon package, service, and configuration.
• Installs the Net-SNMP trap daemon service and configuration.
• Creates a SNMPv3 user with authentication and encryption paswords.

###Beginning with this module

This declaration will get you the SNMP daemon listening on the loopback IPv4 and IPv6 addresses with a v1 and v2c read-only community of 'public'.

include ::snmp

###Upgrading

####Deprecation Warning

The classes snmp::server and snmp::trapd will be merged into class snmp in version 3.0.0 of this module. All of their class parameters will be made available in the snmp class.

The parameter install_client will be renamed to manage_client in version 4.0.0 of this module.

The parameters ro_community, rw_community, ro_network, and rw_network will be removed in version 4.0.0 of this module. The snmptrapd parameter name will become authcommunity.

##Usage

Most interaction with the snmp module can be done through the main snmp class. This means you can simply toggle the parameters in ::snmp to have most functionality of the module. Additional fuctionality can be achieved by only utilizing the ::snmp::client class or the ::snmp::snmpv3_user define.

To install the SNMP service listening on all IPv4 and IPv6 interfaces:

class { 'snmp':
  agentaddress => [ 'udp:161', 'udp6:161' ],
}

To change the SNMP community from the default value and limit the netblocks that can use it:

class { 'snmp':
  agentaddress => [ 'udp:161', ],
  ro_community => 'myPassword',
  ro_network   => '192.168.0.0/16',
}

To set the responsible person and location of the SNMP system:

class { 'snmp':
  contact  => 'root@yourdomain.org',
  location => 'Phoenix, Arizona, U.S.A., Earth, Milky Way',
}

###Client

If you just want to install the SNMP client:

include ::snmp::client

To install the SNMP service and the client:

class { 'snmp':
  manage_client => true,
}

If you want to pass client configuration stanzas to the snmp.conf file:

class { 'snmp':
  snmp_config => [
    'defVersion 2c',
    'defCommunity public',
    'mibdirs +/usr/local/share/snmp/mibs',
  ],
}

###Trap Daemon

To only configure and run the snmptrap daemon:

class { 'snmp':
  service_ensure      => 'stopped',
  trap_service_ensure => 'running',
  trap_service_enable => true,
  snmptrapdaddr       => [ 'udp:162', ],
  trap_handlers       => [
    'default /usr/bin/perl /usr/bin/traptoemail me@somewhere.local', # optional
    'TRAP-TEST-MIB::demo-trap /home/user/traptest.sh demo-trap', # optional
  ],
  trap_forwards       => [ 'default udp:55.55.55.55:162' ], # optional
}

###SNMPv3 Users

To install a SNMP version 3 user for snmpd:

snmp::snmpv3_user { 'myuser':
  authpass => '1234auth',
  privpass => '5678priv',
}
class { 'snmp':
  snmpd_config => [ 'rouser myuser authPriv' ],
}

To install a SNMP version 3 user for snmptrapd:

snmp::snmpv3_user { 'myuser':
  authpass => 'SeCrEt',
  privpass => 'PhRaSe',
  daemon   => 'snmptrapd',
}

###Access Control

With traditional access control, you can give a simple password and (optional) network restriction:

class { 'snmp':
  ro_community => 'myPassword',
  ro_network   => '10.0.0.0/8',
}

and it becomes this in snmpd.conf:

rocommunity myPassword 10.0.0.0/8

This says that any host on network 10.0.0.0/8 can read any SNMP value via SNMP versions 1 and 2c as long as they provide the password 'myPassword'.

With View-based Access Control Model (VACM), you can do this (more complex) configuration instead:

class { 'snmp':
  com2sec  => ['mySecName   10.0.0.0/8 myPassword'],
  groups   => ['myGroupName v1         mySecName',
               'myGroupName v2c        mySecName'],
  views    => ['everyThing  included   .'],
  accesses => ['myGroupName ""      any   noauth  exact  everyThing  none   none'],
}

where the variables have the following meanings:

• "mySecName": A security name you have selected.
• "myPassword": The community (password) for the security name.
• "myGroupName": A group name to which you assign security names.
• "everyThing": A view name (i.e. a list of MIBs that will be ACLed as a unit).

and it becomes this in snmpd.conf:

com2sec mySecName   10.0.0.0/8 myPassword
group   myGroupName v1         mySecName
group   myGroupName v2c        mySecName
view    everyThing  included   .
access  myGroupName ""      any   noauth  exact  everyThing  none   none

This also says that any host on network 10.0.0.0/8 can read any SNMP value via SNMP versions 1 and 2c as long as they provide the password 'myPassword'. But it also gives you the ability to change any of those variables.

Reference: Manpage of snmpd.conf - Access Control

####Multiple Network Restrictions

In traditional access control, you can also pass multiple networks for the community string.

class { 'snmp':
  ro_community => 'shibboleth',
  ro_network   => [ '192.168.0.0/16', '1.2.3.4/32', ],
}

and it becomes this in snmpd.conf:

rocommunity shibboleth 192.168.0.0/16
rocommunity shibboleth 1.2.3.4/32

##Reference

###Classes

• snmp: Installs the Net-SNMP software.
• snmp::client: Separately installs the Net-SNMP client software. Can be called from Class['snmp'].

###Defines

• snmp::snmpv3_user: Creates a SNMPv3 user with authentication and encryption paswords.

###Class: snmp

####Parameters

The following parameters are available in the ::snmp class:

#####agentaddress An array of addresses, on which snmpd will listen for queries. Default: [ udp:127.0.0.1:161, udp6:[::1]:161 ]

#####snmptrapdaddr An array of addresses, on which snmptrapd will listen to receive incoming SNMP notifications. Default: [ udp:127.0.0.1:162, udp6:[::1]:162 ]

#####ro_community Read-only (RO) community string for snmptrap daemon. Default: public

#####ro_community6 Read-only (RO) community string for IPv6. Default: public

#####rw_community Read-write (RW) community string. Default: none

#####rw_community6 Read-write (RW) community string for IPv6. Default: none

#####ro_network Network that is allowed to RO query the daemon. Can be an array. Default: 127.0.0.1

#####ro_network6 Network that is allowed to RO query the daemon via IPv6. Can be an array. Default: ::1/128

#####rw_network Network that is allowed to RW query the daemon. Can be an array. Default: 127.0.0.1

#####rw_network6 Network that is allowed to RW query the daemon via IPv6. Can be an array. Default: ::1/128

#####contact Responsible person for the SNMP system. Default: Unknown

#####location Location of the SNMP system. Default: Unknown

#####sysname Name of the system (hostname). Default: ${::fqdn}

#####services For a host system, a good value is 72 (application + end-to-end layers). Default: 72

#####com2sec An array of VACM com2sec mappings. Must provide SECNAME, SOURCE and COMMUNITY. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbAL for details. Default: [ "notConfigUser default public" ]

#####com2sec6 An array of VACM com2sec6 mappings. Must provide SECNAME, SOURCE and COMMUNITY. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbAL for details. Default: [ "notConfigUser default ${ro_community}" ]

#####groups An array of VACM group mappings. Must provide GROUP, {v1|v2c|usm|tsm|ksm}, SECNAME. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbAL for details. Default: [ 'notConfigGroup v1 notConfigUser', 'notConfigGroup v2c notConfigUser' ]

#####views An array of views that are available to query. Must provide VNAME, TYPE, OID, and [MASK]. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbAL for details. Default: [ 'systemview included .1.3.6.1.2.1.1', 'systemview included .1.3.6.1.2.1.25.1.1' ]

#####accesses An array of access controls that are available to query. Must provide GROUP, CONTEXT, {any|v1|v2c|usm|tsm|ksm}, LEVEL, PREFX, READ, WRITE, and NOTIFY. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbAL for details. Default: [ 'notConfigGroup "" any noauth exact systemview none none' ]

#####dlmod Array of dlmod lines to add to the snmpd.conf file. Must provide NAME and PATH (ex. "cmaX /usr/lib64/libcmaX64.so"). See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbBD for details. Default: []

#####snmpd_config Safety valve. Array of lines to add to the snmpd.conf file. See http://www.net-snmp.org/docs/man/snmpd.conf.html for all options. Default: []

#####disable_authorization Disable all access control checks. (yes|no) Default: no

#####do_not_log_traps Disable the logging of notifications altogether. (yes|no) Default: no

#####do_not_log_tcpwrappers Disable the logging of tcpwrappers messages, e.g. "Connection from UDP: " messages in syslog. (yes|no) Default: no

#####trap_handlers An array of programs to invoke on receipt of traps. Must provide OID and PROGRAM (ex. "IF-MIB::linkDown /bin/traps down"). See http://www.net-snmp.org/docs/man/snmptrapd.conf.html#lbAI for details. Default: [] Affects snmptrapd.conf

#####trap_forwards An array of destinations to send to on receipt of traps. Must provide OID and DESTINATION (ex. "IF-MIB::linkUp udp:1.2.3.5:162"). See http://www.net-snmp.org/docs/man/snmptrapd.conf.html#lbAI for details. Default: [] Affects snmptrapd.conf

#####snmptrapd_config Safety valve. Array of lines to add to the snmptrapd.conf file. See http://www.net-snmp.org/docs/man/snmptrapd.conf.html for all options. Default: [] Affects snmptrapd.conf

#####manage_client Whether to install the Net-SNMP client package. (true|false) Default: false

#####snmp_config Safety valve. Array of lines to add to the client's global snmp.conf file. See http://www.net-snmp.org/docs/man/snmp.conf.html for all options. Default: [] Affects snmp.conf

#####ensure Ensure if present or absent. Default: present

#####autoupgrade Upgrade package automatically, if there is a newer version. Default: false

#####package_name Name of the package. Only set this if your platform is not supported or you know what you are doing. Default: auto-set, platform specific

#####snmpd_options Commandline options passed to snmpd via init script. Default: auto-set, platform specific

#####service_ensure Ensure if service is running or stopped. Default: running

#####service_name Name of SNMP service Only set this if your platform is not supported or you know what you are doing. Default: auto-set, platform specific

#####service_enable Start service at boot. Default: true

#####service_hasstatus Service has status command. Default: true

#####service_hasrestart Service has restart command. Default: true

#####snmptrapd_options Commandline options passed to snmptrapd via init script. Default: auto-set, platform specific

#####trap_service_ensure Ensure if service is running or stopped. Default: stopped

#####trap_service_name Name of SNMP service Only set this if your platform is not supported or you know what you are doing. Default: auto-set, platform specific

#####trap_service_enable Start service at boot. Default: true

#####trap_service_hasstatus Service has status command. Default: true

#####trap_service_hasrestart Service has restart command. Default: true

#####openmanage_enable Adds the smuxpeer directive to the snmpd.conf file to allow net-snmp to talk with Dell's OpenManage. Default: false

###Class: snmp::client

####Parameters

The following parameters are available in the ::snmp::client class:

####snmp_config Array of lines to add to the client's global snmp.conf file. See http://www.net-snmp.org/docs/man/snmp.conf.html for all options. Default: []

####ensure Ensure if present or absent. Default: present

####autoupgrade Upgrade package automatically, if there is a newer version. Default: false

####package_name Name of the package. Only set this if your platform is not supported or you know what you are doing. Default: auto-set, platform specific

###Define: snmp::snmpv3_user

####Parameters

The following parameters are available in the ::snmp::snmpv3_user define:

####title Name of the user. Required

####authpass Authentication password for the user. Required

####authtype Authentication type for the user. SHA or MD5 Default: SHA

####privpass Encryption password for the user. Default: no encryption password

####privtype Encryption type for the user. AES or DES Default: AES

####daemon Which daemon file in which to write the user. snmpd or snmptrapd Default: snmpd

##Limitations

###OS Support:

Net-SNMP module support is available with these operating systems:

• RedHat family - tested on CentOS 5.9, CentOS 6.6, and CentOS 7.0
• SuSE family - tested on SLES 11 SP1
• Debian family - tested on Ubuntu 12.04.2 LTS, Debian 6.0.7, and Debian 7.0
• FreeBSD family - tested on FreeBSD 9.2-RELEASE, FreeBSD 10.0-RELEASE

###Notes:

• By default the SNMP service now listens on BOTH the IPv4 and IPv6 loopback addresses.
• Only tested on CentOS 5.9, CentOS 6.6, CentOS 7.0, Ubuntu 12.04.2 LTS, Debian squeeze, and Debian wheezy x86_64.
• SNMPv3 user auth is not yet tested on Debian or Suse osfamilies.
• There is a bug on Debian squeeze of net-snmp's status script. If snmptrapd is not running the status script returns 'not running' so puppet restarts the snmpd service. The following is a workaround: class { 'snmp': service_hasstatus => false, trap_service_hasstatus => false, }
• For security reasons, the SNMP daemons are configured to listen on the loopback interfaces (127.0.0.1 and [::1]). Use agentaddress and snmptrapdaddr to change this configuration.
• Not all parts of Traditional Access Control or VACM Configuration are fully supported in this module.

###Issues:

• Debian will not support the use of non-numeric OIDs. Something about rabid freedom.
• Figure out how to install the RFC-standard MIBS on Debian so that snmpwalk -v 2c -c public localhost system will function.
• Possibly support USM and VACM?

##Development

Please see DEVELOP.md for information on how to contribute.

Copyright (C) 2012 Mike Arnold mike@razorsedge.org

Licensed under the Apache License, Version 2.0.

razorsedge/puppet-snmp on GitHub

razorsedge/snmp on Puppet Forge

2015-10-14 Michael Arnold github@razorsedge.org - 3.5.0

Michael Arnold github@razorsedge.org (3):

• Update docs for GH-55.

• Updated unit tests to pass for changes in GH-42.

• Update versions for 3.5.0 release.

  Peter Keel keel@atrila.com (2):

• quote snmpv3 passphrases to cope with weird characters and spaces

• Somehow a backslash got lost. fixed

  rmenezes rmenezes@shark.localdomain (1):

• Add the ability pass multiple networks for the community string

2015-07-06 Michael Arnold github@razorsedge.org - 3.4.0

Michael Arnold github@razorsedge.org (23):

• Update rspec-puppet ~> 2.0 and metadata-json-lint >= 0.0.4 with modulesync.

• 'subject' method no longer exists in rspec-puppet.

• Fix puppetlint rake task with modulesync.

• Stick with rspec 2 for unit tests.

• Shorten metadata summary to less than 144 characters.

• Set EL7 options to work with systemd.

• Add rspec tests specifically for EL5.

• Get code ready for Puppet 4.

• Fix lint: class included by relative name.

• Fix lint: variable assigned to the empty string.

• Update Puppet 4 gem and support puppet_blacksmith with modulesync.

• Update Geppetto .project.

• Unit test against Puppet 4 via modulesync.

• Now supporting Puppet 4.

• Fix rwcommmunity6 typo.

• Convert to new README.markdown format.

• Added Access Control section to README.markdown.

• Improvements to README.markdown.

• Shorten metadata.json summary to 144 characters.

• Better define Access Control variables in README.

• Add links in the reference section of the README.

• Add a pause after service stop and before creating SNMPv3 users.

• Update versions for 3.4.0 release.

  Brett Delle Grazie brett.dellegrazie@indigoblue.co.uk (1):

• skip zero length strings in ERB template output

  Markus Heberling markus@tisoft.de (1):

• fixed a small typo in example

  typo101 typo101@clemnet.info (1):

• fix typo in freebsd config dir perms and ownership

2015-01-03 Michael Arnold github@razorsedge.org - 3.3.1

Michael Arnold github@razorsedge.org (4):

• Enable rocommunity/rwcommunity in snmpd.conf.
• Update metadata.json.
• Manage .puppet-lint.rc with modulesync.
• Update versions for 3.3.1 release.

2014-12-28 Michael Arnold github@razorsedge.org - 3.3.0

Erinn Looney-Triggs erinn.looneytriggs@gmail.com (14):

• Add in basic IPv6 support.

• Typo of variable.

• Add com2sec6.

• Fix tests to pass for IPv6.

• Add in the ability to quiet logging for SNMP service.

• Fix typo in template.

• Add tests for the disable logging option.

• Additional test for when do_not_log_tcpwrappers is set to yes.

• Added openmanage directives.

• Add tests for openmanage snmpd.conf additions.

• Validate openmanage boolean.

• Add documentation and change com2sec6 to use public string by default.

• Add additional IPv6 tests.

• Update tested on list.

  Michael Arnold github@razorsedge.org (6):

• Deprecate the use of ro_community and friends.

• Fix typo 'paramter' in README.md.

• Fix license and unbounded ranges in metadata.json.

• Add metadata-json-lint support to Gemfile and Rakefile.

• Manage common files with modulesync.

• Update versions for 3.3.0 release.

2014-10-06 Michael Arnold github@razorsedge.org - 3.2.0

Michael Arnold github@razorsedge.org (12):

• Update Geppetto .project to version 4.

• Allow tracking of metadata.json.

• Expand Puppet versions tested in Travis-CI.

• Fix lint indentation warnings.

• Switch to using metadata.json vs Modulefile.

• Add missing dependency values to metadata.json.

• Change the order of the tags in metadata.json.

• Rename install_client param to manage_client.

• Remove rspec test for deprecation warning.

• Allow for setting sysName.

• Update to newer Gemfile, Rakefile, and spec_helper.

• Update versions for 3.2.0 release.

  Sebastian Brückner sebbrueckner@gmail.com (1):

• Fix variable names to be lowercase for future parser compatibility.

2014-05-25 Michael Arnold github@razorsedge.org - 3.1.0

Michael Arnold github@razorsedge.org (7):

• Add contribution instructions to README.md.

• Convert fixtures repositories to use https.

• Expand Puppet versions tested in Travis-CI.

• Add compatibility data to the module.

• Update README.md with details about issue #9.

• Update Modulefile source to use https.

• Update versions for 3.1.0 release.

  Hunter Satterwhite hsatterwhite@webassign.net (6):

• Added FreeBSD support

• Fixed service config path

• Added variable for group ownership for snmpd.conf/snmptrapd.conf

• Added spec test for FreeBSD

• Updated README.md

• snmp client test for FreeBSD

  Clint Miller clintmiller@mac.com (1):

• Create 'services' parameter to snmp class

  Steve Maddison steve@cosam.org (1):

• Support for custom VACM com2sec and group mappings.

2013-07-13 Michael Arnold github@razorsedge.org - 3.0.0

Michael Arnold github@razorsedge.org (31):

• Clarify that this module installs the Net-SNMP software.

• Fix README.md title.

• Remove the dependency on LSB facts.

• Major refactor of server/trap/client classes.

• Templatize config files.

• Update example config files.

• Convert the remaining parameters to support ENC.

• Fix README.md markdown.

• Squash bugs via live testing.

• Fix trapd service on Debian.

• Add more Puppet tests.

• Add more rspec tests.

• Added Suse osfamily support.

• Renamed files directory to be samples.

• Fix arrow alignment to make lint happy.

• Add support for sysservices.

• Rake validate to also check ERB for syntax errors.

• Add support for dlmod.

• Implement configuration safety valves.

• Add agentaddress and snmptrapdaddr parameters.

• Refactor SNMP configs.

• Enhanced snmpv3_user to also create snmptrapd users.

• Expand Puppet versions tested in Travis-CI.

• Fix an Rspec error seen on Ruby 1.9.3+.

• Fix wyrie-trapd_extended additions to support ENC.

• Rename snmp_trap_addr to snmptrapdaddr.

• Make agentaddress an array like snmptrapdaddr.

• Standardize parameter->template results.

• Remove git-log-to-changelog from Modulefile.

• Update README.md with new changes.

• Update versions for 3.0.0 release.

  Scott Barr scott@barr.co.za (3):

• • Extend functionality by adding class parameters: snmp_trap_addr
    disable_authorization do_not_log_traps

• The trap_handlers class parameter accepts any values and is directly outputted to the template, essentially allowing any value to be written to file. Prefix each value in trap_handler with 'traphandle' for a more expected/sane result.

• Added forwards for notification processing.

2013-06-22 Michael Arnold github@razorsedge.org - 2.0.0

Michael Arnold github@razorsedge.org (20):

• Fix Ubuntu support to pass lint

• Update Travis-CI config file to test 2.7.18

• Update rspec tests for new rspec version.

• Initial Ubuntu support rspec tests

• Converted to puppetlabs_spec_helper.

• Updated .travis.yml and .gemfile.

• Add CHANGELOG generation during module build.

• Lint: fix variable not enclosed in {}.

• Fix Ubuntu support to pass lint

• Initial Ubuntu support rspec tests

• Do not install File['snmptrapd.sysconfig'] on Debian.

• Add files/snmpd.sysconfig-Debian-12.

• Initial Debian support rspec tests.

• Clean up Notes section of README.md.

• Use ::osfamily instead of ::operatingsystem.

• Convert template variables to be local.

• Added deprecation warnings in README.md.

• Fix support for snmptrapd on Debian.

• Update README.md.

• Update versions for 2.0.0 release.

  Endre Karlson endre.karlson@gmail.com (2):

• Add Ubuntu support and fix indent

• Add Ubuntu support and fix indent

  Jonathan Owens jonathan@newrelic.com (2):

• Allow overriding the list of views and accesses.

• Allow specifying traphandlers for trapd.

  Santiago Piccinini spiccinini@codigosur.org (1):

• Added initial support for Debian

2012-07-15 Michael Arnold github@razorsedge.org - 1.0.2

Michael Arnold github@razorsedge.org (1):

• Bump module version for Puppet Forge release

  Steve Huff shuff@vecna.org (1):

• modified templates to dereference class parameters

2012-05-26 Michael Arnold github@razorsedge.org - 1.0.1

Michael Arnold github@razorsedge.org (1):

• Change github account to razorsedge

2012-05-06 Michael Arnold github@razorsedge.org - 1.0.0