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
   • 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

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.

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.

• 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.

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

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.

Support for Puppet 2.7 will be removed in version 4.0.0 of this module.

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',
}

Or more than one community:

class { 'snmp':
  agentaddress => [ 'udp:161', ],
  ro_community => [ 'myPassword', 'myOtherPassword', ],
}

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

class { 'snmp':
  contact  => '[email protected]',
  location => 'Phoenix, Arizona, U.S.A., Earth, Milky Way',
}

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',
  ],
}

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 [email protected]', # optional
    'TRAP-TEST-MIB::demo-trap /home/user/traptest.sh demo-trap', # optional
  ],
  trap_forwards       => [ 'default udp:55.55.55.55:162' ], # optional
}

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',
}

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

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

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

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

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

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

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

Read-only (RO) community string or array for snmptrap daemon. Default: public

Read-only (RO) community string or array for IPv6. Default: public

Read-write (RW) community string or array. Default: none

Read-write (RW) community string or array for IPv6. Default: none

Network that is allowed to RO query the daemon. Can be string or array. Default: 127.0.0.1

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

Network that is allowed to RW query the daemon. Can be string or array. Default: 127.0.0.1

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

Responsible person for the SNMP system. Default: Unknown

Location of the SNMP system. Default: Unknown

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

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

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" ]

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}" ]

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' ]

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' ]

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' ]

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: []

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 all access control checks. (yes|no) Default: no

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

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

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

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

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

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

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 if present or absent. Default: present

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

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

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

Ensure if service is running or stopped. Default: running

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

Start service at boot. Default: true

Service has status command. Default: true

Service has restart command. Default: true

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

Ensure if service is running or stopped. Default: stopped

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

Start service at boot. Default: true

Service has status command. Default: true

Service has restart command. Default: true

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

Allow setting the master option, typically to enable AgentX registrations. Default: false

Defines the permissions and ownership of the AgentX Unix Domain socket. Default: none

This will make the subagent try and reconnect every NUM seconds to the master if it ever becomes (or starts) disconnected. Default: none

Defines the address the master agent listens at, or the subagent should connect to. Default: none

Defines the timeout period (NUM seconds) for an AgentX request. Default: 1

Defines the number of retries for an AgentX request. Default: 5

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

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 if present or absent. Default: present

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

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

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

Name of the user. Required

Authentication password for the user. Required

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

Encryption password for the user. Default: no encryption password

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

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

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
• OpenBSD family - tested on OpenBSD 5.9

• 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.

• 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?

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

Copyright (C) 2012 Mike Arnold [email protected]

Licensed under the Apache License, Version 2.0.

razorsedge/puppet-snmp on GitHub

razorsedge/snmp on Puppet Forge