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

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

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

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  => '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 or array for snmptrap daemon. Default: public

ro_community6

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

rw_community

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

rw_community6

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

ro_network

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

ro_network6

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

rw_network

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

rw_network6

Network that is allowed to RW query the daemon via IPv6. Can be string or 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: []

extends

Array of extend lines to add to the snmpd.conf file. Must provide NAME, PROG and ARG. See http://www.net-snmp.org/docs/man/snmpd.conf.html#lbBA 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

master

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

agentx_perms

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

agentx_ping_interval

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

agentx_socket

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

agentx_timeout

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

agentx_retries

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

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, Debian 7.0, and Debian 9.
• FreeBSD family - tested on FreeBSD 9.2-RELEASE, FreeBSD 10.0-RELEASE
• OpenBSD family - tested on OpenBSD 5.9

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