This document targets people who have to administer smart-snmpd, either because they operate machines with smart-snmpd running or they have to configure reasonable default installations for packaging or automated deployment.
Packagers should read the INSTALL document first.
The build procedure of smart-snmpd creates and installs an example configuration file into $sysconfdir ($prefix/etc) named smart-snmpd.conf.example. You need to copy this file into a file named smart-snmpd.conf and modify it to fit your requirements. The task of copying this configuration file might be allocated to the post-install script of a package.
The file smart-snmpd.conf.example is extensively documented; it is strongly recommended you keep the comments when editing the configuration file in daily business.
Note that unspecified values are set to reasonable defaults.
These settings affect all (or at least multiple) components of the smart-snmpd:
Setting | Data Type | Restriction | Description |
daemonize | boolean | - | When set true (default), smart-snmpd will daemonize when started |
port | integer | > 0 | Specifies the port to listen on, but listen on all available interfaces / addresses |
listen-on | string | must include port | Specifies the UDP address to listen on (IPv4 or IPv6 address and port) |
status-file | string | - | Specifies the fully qualified path name (FQPN) to the file to store the status of the snmpd |
pid-file | string | - | Specifies the FQPN to the pid-file to use |
job-threads1 | integer | > 0 | Specifies the number of threads which will be used to answer snmp requests |
rlimits | struct | - | Provides settings for the (soft) resource limits of the daemon for core (RLIMIT_CORE), cpu (RLIMIT_CPU), data (RLIMIT_DATA), filesize (RLIMIT_FSIZE), files (RLIMIT_NOFILE), stack (RLIMIT_STACK) and mem (RLIMIT_AS). Allowed values are: integer (specifying an absolute limit), ”unlimited”, ”soft” (current set soft limit), ”hard (current set hard limit)”. If not specified, the default is ”soft”. |
on-fatal2 | enum | - | defines the action on fatal errors (ERROR_LOG with log-level 0) - possible values: ignore, raise, kill (default), exit, _exit, abort |
su-cmd3 | string | - | Command to use to execute an external command as a specific user |
su-args3 | string | - | Arguments for above command |
Note that the last three actions might not flush all logging messages
3 only with libjson (bundled or separate) and --with-su-cmd enabled in
configuration
Example:
These settings affect the logging behavior of smart-snmpd and are only available when logging support wasn’t disabled in snmp++.
Setting | Data Type | Description |
log-file1 | string | Specifies the FQPN of the file to write logs to |
log4cplus-property-file2 | string | Specifies the FQPN of the property file to configure log4cplus |
log-profile3 | string | Specifies the log-profile to use. In addition to the 9 profiles provided by snmp++, a profile named ”individual” is provided which means ”Use the individual log level configuration in log-class”. |
log-class | struct | Defines each each log-level per class (error, warning, event, info, debug, user4) individually. Permitted values are -1 for disabled and a threshold value from 0 to 15. |
Example:
These settings affect the wy statistics are collected with libstatgrab. Currently only file systems can be filtered.
Setting | Data Type | Description |
valid-filesystems | list | Specifies a list of file system types to collect statistics for. With a ”!” as first item the specified list is subtracted from the initial list of valid file systems |
Example:
The built-in basic MIBs are setup using either the mibobject or inrobject. The mibobject structure initializes the basic configuration settings of all managed smart-snmpd MIBs:
Setting | Data Type | Description |
mib-enabled | boolean | Specifies whether this MIB object is enabled and can be requested or not. By default all built-in mibs are enabled. |
async-update | boolean | Specifies whether this MIB object will be updated asynchronously in a background thread or synchronously every time when requested. By default a MIB is updated synchronously. |
cache-timeout | integer | Time in seconds before the data cache of a MIB object becomes invalid and must be refreshed. This happens all 30 seconds by default. |
Example:
Several MIBs support differences, too. Those MIBs can be configured using the inrobject which contains all settings of mibobject and extends it with:
Setting | Data Type | Description |
mr-interval | integer | Time in seconds of the most-recent interval to calculate the difference. The value must be a multiple of cache-timeout. Note: If no interval is given, the value of cache-timeout is used which results in a diff between the most current value set and the one before. |
It is strongly recommended you configure a MIB object which delivers differences to be updated asynchronously via a background thread. Without this, it is not guaranteed that the difference time slices are valid. In the case of a synchronous configuration, smart-snmpd will issue out a warning.
If you do not configure eg. CpuUsage using the inrobject section, but mibobject, the most recent cache interval is by default set to the value of cache-timeout. This means at least the difference from the last statistics is kept.
Example:
smart-snmpd supports MIBs from external commands in addition to the planned AgentX support. Those external command MIBs are designed for performance - the AgentX protocol slows down mass data retrieves.
The external command MIBs are below 1.3.6.1.4.1.36539.20 and need to be specified for each tree separately in the configuration using the extobject group, which extends the mibobject specification as follows:
Setting | Data Type | Description |
command | string | Specifies the FQPN to the command to execute and the full arguments as a shell expression |
args | list of strings | Specifies the arguments passed to the executed command |
user1 | string | Specifies the name of the user to switch to for command execution. |
sub-oid | integer | specifies the oid below 1.3.6.1.4.1.36539.20 where the received data should be addressed. |
rlimits | struct | Allows setting the current (soft) resource limits for the executed process for core (RLIMIT_CORE), cpu (RLIMIT_CPU), data (RLIMIT_DATA), filesize (RLIMIT_FSIZE), files (RLIMIT_NOFILE), stack (RLIMIT_STACK) and mem (RLIMIT_AS) individually. Allowed values are: absolute limit (integer), unlimited, soft (soft limit at daemon start), hard (hard limit at daemon start). |
If you configure a MIB for an external object using mibobject instead of extobject, no external command will be known and the MIB will remain empty.
Example:
The following built-in MIB objects need settings from …
MIB Object | OID | Setting Structure |
DaemonStatus | 1.3.6.1.4.1.36539.10.1 | mibobject |
HostInfo | 1.3.6.1.4.1.36539.10.2 | mibobject |
CpuUsage | 1.3.6.1.4.1.36539.10.3 | inrobject |
MemoryUsage | 1.3.6.1.4.1.36539.10.4 | mibobject |
SystemLoad | 1.3.6.1.4.1.36539.10.5 | mibobject |
UserLogins | 1.3.6.1.4.1.36539.10.6 | mibobject |
ProcessStatus | 1.3.6.1.4.1.36539.10.7 | mibobject |
FileSystemUsage | 1.3.6.1.4.1.36539.10.8 | mibobject |
DiskIO | 1.3.6.1.4.1.36539.10.20 | inrobject |
NetworkIO | 1.3.6.1.4.1.36539.10.21 | inrobject |
SwapIO | 1.3.6.1.4.1.36539.10.22 | inrobject |
AppMonitoring | 1.3.6.1.4.1.36539.20.1 | extobject |
Memorize that
is the same as
Future Task (Unimplemented)
Future Task (Unimplemented)
smart-snmpd implements full SNMPv3 access control via embedded agent++ library. For the specification see http://www.ietf.org/rfc/rfc3415.txt.
To configure SNMPv3 VACM, the following structures should be used:
Setting | Data Type | Values | Description |
auth-proto | enum | none, md5, sha | hash algorithm for auth-key |
auth-key | string |
| the authentication key |
priv-proto | enum | none, des, 3des*, idea*, aes1, aes128, aes192*, aes256*, | encryption algorithm for priv-key |
priv-key | string |
| the private key |
The security name is taken from the section title of the individual user sections specified in the configuration file.
Setting | Data Type | Values | Description |
security-model | enum | usm | Currently the one and only valid security model is USM |
security-name | list of strings | Name of defined user | List of users (mapped to security name) valid for this group |
storage-type | enum | other, volatile, nonvolatile, permanent, readonly | storage type for this entry |
The group name is taken from the section title of the individual group sections specified in the configuration file.
Setting | Data Type | Values | Description |
sub-tree | OID | OID1 | Valid, managed OID or a parent of any |
mask | Hex Integer | Bitmask as hexadecimal string | See ViewTreeFamily description in RFC-3415 |
view-type | enum | included, excluded | include or exclude this view tree |
storage-type | enum | other, volatile, nonvolatile, permanent, readonly | storage type for this entry |
Setting | Data Type | Values | Description |
group-name | string | Name of defined group | Name of group whose access configuration is done here |
context | string |
| Context name for this configuration |
security-model | enum | usm | Currently the one and only valid security model is USM |
security-level | enum | none, noauth1,2, nopriv1,2, auth1,2, priv1,2 | Security level for this access entry |
match | enum |
| … |
read-view | string / reference | Name of defined view | Read view for this access entry |
write-view | string / reference | Name of defined view | Write view for this access entry |
notify-view | string / reference | Name of defined view | Notify view for this access entry |
storage-type | enum | other, volatile, nonvolatile, permanent, readonly | storage type for this entry |
The available command line arguments are displayed when smart-snmpd is called using the ”-h” switch. The one which will be discussed here in detail is -k. Using the -k command line switch allows you to choose the action to run from start (default), stop, restart, graceful, reload, check, kill.
Action Name | Action Description |
start | starts the Smart-SNMP-Daemon |
stop | Stops the currently running Smart-SNMP-Daemon. Requests in the queue are answered (up to 2 seconds*). |
restart | Restarts1 the currently running Smart-SNMP-Daemon. Requests in the queue aren’t answered. |
graceful | Gracefully restarts the currently running Smart-SNMP-Daemon. Requests in the queue are answered (up to 2 seconds*). |
reload | Reloads2 the configuration of the currently running Smart-SNMP-Daemon |
check | Performs a check of the configuration file of the Smart-SNMP-Daemon |
kill | Kills1 the currently running Smart-SNMP-Daemon |
Runtime settings, which are refreshed when the smart-snmpd catches a SIGHUP signal, are:
In some circumstances it is reasonable to temporarily override some configuration settings. You can do this from the command line when starting the daemon (and only then) by specifying one or more of following options:
An already running daemon cannot be forced to reload into the foreground (or vice versa), you need to restart the daemon with appropriate -d or -D switch.
Note: command line switches are valid until the daemon ends or gets restarted with different command line switches. There is no way to override such settings without stopping the daemon at least for a moment.
The Smart-Snmpd has temporary and permanent requirements to operate.
The permanent requirements are:
The temporary requirements are:
Command line arguments always override configuration file settings and default behaviours as described in ”Setting up and Run a Simple Smart-Snmpd” (Section 2.1).
Usually you do not want to run a local smart-snmpd using elevated privileges. That implies, the daemon can neither bind to port 161 nor modify $prefix/var/run/smart-snmpd.pid nor any other required status file (as the boot counter). It implies further, that some statistics might be incomplete or unavailable, depending on the underlying operating system.
Thus you need to override those file locations using
Unimplemented.
Unimplemented.
Partial working.
Future Task