- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with this module
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- 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 fromClass['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: []
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: []
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, 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
- 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
andsnmptrapdaddr
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.