diff options
Diffstat (limited to 'collectors/freeipmi.plugin/README.md')
| -rw-r--r-- | collectors/freeipmi.plugin/README.md | 141 |
1 files changed, 111 insertions, 30 deletions
diff --git a/collectors/freeipmi.plugin/README.md b/collectors/freeipmi.plugin/README.md index 47decd7ff..5a9fd93c0 100644 --- a/collectors/freeipmi.plugin/README.md +++ b/collectors/freeipmi.plugin/README.md @@ -11,7 +11,10 @@ learn_rel_path: "Integrations/Monitor/Devices" Netdata has a [freeipmi](https://www.gnu.org/software/freeipmi/) plugin. -> FreeIPMI provides in-band and out-of-band IPMI software based on the IPMI v1.5/2.0 specification. The IPMI specification defines a set of interfaces for platform management and is implemented by a number vendors for system management. The features of IPMI that most users will be interested in are sensor monitoring, system event monitoring, power control, and serial-over-LAN (SOL). +> FreeIPMI provides in-band and out-of-band IPMI software based on the IPMI v1.5/2.0 specification. The IPMI +> specification defines a set of interfaces for platform management and is implemented by a number vendors for system +> management. The features of IPMI that most users will be interested in are sensor monitoring, system event monitoring, +> power control, and serial-over-LAN (SOL). ## Installing the FreeIPMI plugin @@ -22,7 +25,8 @@ installed automatically due to the large number of dependencies it requires. When using a static build of Netdata, the FreeIPMI plugin will be included and installed automatically, though you will still need to have FreeIPMI installed on your system to be able to use the plugin. -When using a local build of Netdata, you need to ensure that the FreeIPMI development packages (typically called `libipmimonitoring-dev`, `libipmimonitoring-devel`, or `freeipmi-devel`) are installed when building Netdata. +When using a local build of Netdata, you need to ensure that the FreeIPMI development packages (typically +called `libipmimonitoring-dev`, `libipmimonitoring-devel`, or `freeipmi-devel`) are installed when building Netdata. ### Special Considerations @@ -30,7 +34,9 @@ Accessing IPMI requires root access, so the FreeIPMI plugin is automatically ins FreeIPMI does not work correctly on IBM POWER systems, thus Netdata’s FreeIPMI plugin is not usable on such systems. -If you have not previously used IPMI on your system, you will probably need to run the `ipmimonitoring` command as root to initiailze IPMI settings so that the Netdata plugin works correctly. It should return information about available seensors on the system. +If you have not previously used IPMI on your system, you will probably need to run the `ipmimonitoring` command as root +to initiailze IPMI settings so that the Netdata plugin works correctly. It should return information about available +seensors on the system. In some distributions `libipmimonitoring.pc` is located in a non-standard directory, which can cause building the plugin to fail when building Netdata from source. In that case you @@ -38,37 +44,68 @@ should find the file and link it to the standard pkg-config directory. Usually, /usr/lib/$(uname -m)-linux-gnu/pkgconfig/libipmimonitoring.pc/libipmimonitoring.pc /usr/lib/pkgconfig/libipmimonitoring.pc` resolves this issue. -## Netdata use +## Metrics -The plugin creates (up to) 8 charts, based on the information collected from IPMI: +The plugin does a speed test when it starts, to find out the duration needed by the IPMI processor to respond. Depending +on the speed of your IPMI processor, charts may need several seconds to show up on the dashboard. -1. number of sensors by state -2. number of events in SEL -3. Temperatures CELSIUS -4. Temperatures FAHRENHEIT -5. Voltages -6. Currents -7. Power -8. Fans +Metrics grouped by *scope*. -It also adds 2 alarms: +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. -1. Sensors in non-nominal state (i.e. warning and critical) -2. SEL is non empty +### global - +These metrics refer to the monitored host. -The plugin does a speed test when it starts, to find out the duration needed by the IPMI processor to respond. Depending on the speed of your IPMI processor, charts may need several seconds to show up on the dashboard. +This scope has no labels. -## `freeipmi.plugin` configuration +Metrics: + +| Metric | Dimensions | Unit | +|----------|:----------:|:------:| +| ipmi.sel | events | events | + +### sensor + +These metrics refer to the sensor. + +Labels: + +| Label | Description | +|-----------|-----------------------------------------------------------------------------------------------------------------| +| sensor | Sensor name. Same value as the "Name" column in the `ipmi-sensors` output. | +| type | Sensor type. Same value as the "Type" column in the `ipmi-sensors` output. | +| component | General sensor component. Identified by Netdata based on sensor name and type (e.g. System, Processor, Memory). | + +Metrics: + +| Metric | Dimensions | Unit | +|-----------------------------|:-----------------------------------:|:----------:| +| ipmi.sensor_state | nominal, critical, warning, unknown | state | +| ipmi.sensor_temperature_c | temperature | Celsius | +| ipmi.sensor_temperature_f | temperature | Fahrenheit | +| ipmi.sensor_voltage | voltage | Volts | +| ipmi.sensor_ampere | ampere | Amps | +| ipmi.sensor_fan_speed | rotations | RPM | +| ipmi.sensor_power | power | Watts | +| ipmi.sensor_reading_percent | percentage | % | + +## Alarms + +There are 2 alarms: + +- The sensor is in a warning or critical state. +- System Event Log (SEL) is non-empty. + +## Configuration The plugin supports a few options. To see them, run: ```text -# /usr/libexec/netdata/plugins.d/freeipmi.plugin -h +# ./freeipmi.plugin --help - netdata freeipmi.plugin 1.8.0-546-g72ce5d6b_rolling - Copyright (C) 2016-2017 Costa Tsaousis <costa@tsaousis.gr> + netdata freeipmi.plugin v1.40.0-137-gf162c25bd + Copyright (C) 2023 Netdata Inc. Released under GNU General Public License v3 or later. All rights reserved. @@ -86,17 +123,49 @@ The plugin supports a few options. To see them, run: no-sel enable/disable SEL collection default: enabled + reread-sdr-cache re-read SDR cache on every iteration + default: disabled + + interpret-oem-data attempt to parse OEM data + default: disabled + + assume-system-event-record + tread illegal SEL events records as normal + default: disabled + + ignore-non-interpretable-sensors + do not read sensors that cannot be interpreted + default: disabled + + bridge-sensors bridge sensors not owned by the BMC + default: disabled + + shared-sensors enable shared sensors, if found + default: disabled + + no-discrete-reading do not read sensors that their event/reading type code is invalid + default: enabled + + ignore-scanning-disabled + Ignore the scanning bit and read sensors no matter what + default: disabled + + assume-bmc-owner assume the BMC is the sensor owner no matter what + (usually bridging is required too) + default: disabled + hostname HOST username USER password PASS connect to remote IPMI host default: local IPMI processor + no-auth-code-check noauthcodecheck don't check the authentication codes returned - driver-type IPMIDRIVER - Specify the driver type to use instead of doing an auto selection. - The currently available outofband drivers are LAN and LAN_2_0, - which perform IPMI 1.5 and IPMI 2.0 respectively. + driver-type IPMIDRIVER + Specify the driver type to use instead of doing an auto selection. + The currently available outofband drivers are LAN and LAN_2_0, + which perform IPMI 1.5 and IPMI 2.0 respectively. The currently available inband drivers are KCS, SSIF, OPENIPMI and SUNBMC. sdr-cache-dir PATH directory for SDR cache files @@ -105,9 +174,15 @@ The plugin supports a few options. To see them, run: sensor-config-file FILE filename to read sensor configuration default: system default + sel-config-file FILE filename to read sel configuration + default: system default + ignore N1,N2,N3,... sensor IDs to ignore default: none + ignore-status N1,N2,N3,... sensor IDs to ignore status (nominal/warning/critical) + default: none + -v -V version print version and exit @@ -131,13 +206,17 @@ You can set these options in `/etc/netdata/netdata.conf` at this section: command options = ``` -Append to `command options =` the settings you need. The minimum `update every` is 5 (enforced internally by the plugin). IPMI is slow and CPU hungry. So, once every 5 seconds is pretty acceptable. +Append to `command options =` the settings you need. The minimum `update every` is 5 (enforced internally by the +plugin). IPMI is slow and CPU hungry. So, once every 5 seconds is pretty acceptable. ## Ignoring specific sensors -Specific sensor IDs can be excluded from freeipmi tools by editing `/etc/freeipmi/freeipmi.conf` and setting the IDs to be ignored at `ipmi-sensors-exclude-record-ids`. **However this file is not used by `libipmimonitoring`** (the library used by Netdata's `freeipmi.plugin`). +Specific sensor IDs can be excluded from freeipmi tools by editing `/etc/freeipmi/freeipmi.conf` and setting the IDs to +be ignored at `ipmi-sensors-exclude-record-ids`. **However this file is not used by `libipmimonitoring`** (the library +used by Netdata's `freeipmi.plugin`). -So, `freeipmi.plugin` supports the option `ignore` that accepts a comma separated list of sensor IDs to ignore. To configure it, edit `/etc/netdata/netdata.conf` and set: +So, `freeipmi.plugin` supports the option `ignore` that accepts a comma separated list of sensor IDs to ignore. To +configure it, edit `/etc/netdata/netdata.conf` and set: ``` [plugin:freeipmi] @@ -196,7 +275,9 @@ You can also permanently set the above setting by creating the file `/etc/modpro options ipmi_si kipmid_max_busy_us=10 ``` -This instructs the kernel IPMI module to pause for a tick between checking IPMI. Querying IPMI will be a lot slower now (e.g. several seconds for IPMI to respond), but `kipmi` will not use any noticeable CPU. You can also use a higher number (this is the number of microseconds to poll IPMI for a response, before waiting for a tick). +This instructs the kernel IPMI module to pause for a tick between checking IPMI. Querying IPMI will be a lot slower +now (e.g. several seconds for IPMI to respond), but `kipmi` will not use any noticeable CPU. You can also use a higher +number (this is the number of microseconds to poll IPMI for a response, before waiting for a tick). If you need to disable IPMI for Netdata, edit `/etc/netdata/netdata.conf` and set: |