diff options
Diffstat (limited to 'collectors/freeipmi.plugin')
| l---------[-rw-r--r--] | collectors/freeipmi.plugin/README.md | 288 | ||||
| -rw-r--r-- | collectors/freeipmi.plugin/freeipmi_plugin.c | 10 | ||||
| -rw-r--r-- | collectors/freeipmi.plugin/integrations/intelligent_platform_management_interface_ipmi.md | 274 | ||||
| -rw-r--r-- | collectors/freeipmi.plugin/metadata.yaml | 238 |
4 files changed, 498 insertions, 312 deletions
diff --git a/collectors/freeipmi.plugin/README.md b/collectors/freeipmi.plugin/README.md index 5a9fd93c0..f55ebf73d 100644..120000 --- a/collectors/freeipmi.plugin/README.md +++ b/collectors/freeipmi.plugin/README.md @@ -1,287 +1 @@ -<!-- -title: "freeipmi.plugin" -custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/freeipmi.plugin/README.md" -sidebar_label: "freeipmi.plugin" -learn_status: "Published" -learn_topic_type: "References" -learn_rel_path: "Integrations/Monitor/Devices" ---> - -# freeipmi.plugin - -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). - -## Installing the FreeIPMI plugin - -When using our official DEB/RPM packages, the FreeIPMI plugin is included in a separate package named -`netdata-plugin-freeipmi` which needs to be manually installed using your system package manager. It is not -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. - -### Special Considerations - -Accessing IPMI requires root access, so the FreeIPMI plugin is automatically installed setuid root. - -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. - -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 -should find the file and link it to the standard pkg-config directory. Usually, running `sudo ln -s -/usr/lib/$(uname -m)-linux-gnu/pkgconfig/libipmimonitoring.pc/libipmimonitoring.pc /usr/lib/pkgconfig/libipmimonitoring.pc` -resolves this issue. - -## Metrics - -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. - -Metrics grouped by *scope*. - -The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. - -### global - -These metrics refer to the monitored host. - -This scope has no labels. - -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 -# ./freeipmi.plugin --help - - 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. - - This program is a data collector plugin for netdata. - - Available command line options: - - SECONDS data collection frequency - minimum: 5 - - debug enable verbose output - default: disabled - - sel - 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. - The currently available inband drivers are KCS, SSIF, OPENIPMI and SUNBMC. - - sdr-cache-dir PATH directory for SDR cache files - default: /tmp - - 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 - - Linux kernel module for IPMI is CPU hungry. - On Linux run this to lower kipmiN CPU utilization: - # echo 10 > /sys/module/ipmi_si/parameters/kipmid_max_busy_us - - or create: /etc/modprobe.d/ipmi.conf with these contents: - options ipmi_si kipmid_max_busy_us=10 - - For more information: - https://github.com/netdata/netdata/tree/master/collectors/freeipmi.plugin -``` - -You can set these options in `/etc/netdata/netdata.conf` at this section: - -``` -[plugin:freeipmi] - update every = 5 - 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. - -## 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`). - -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] - command options = ignore 1,2,3,4,... -``` - -To find the IDs to ignore, run the command `ipmimonitoring`. The first column is the wanted ID: - -``` -ID | Name | Type | State | Reading | Units | Event -1 | Ambient Temp | Temperature | Nominal | 26.00 | C | 'OK' -2 | Altitude | Other Units Based Sensor | Nominal | 480.00 | ft | 'OK' -3 | Avg Power | Current | Nominal | 100.00 | W | 'OK' -4 | Planar 3.3V | Voltage | Nominal | 3.29 | V | 'OK' -5 | Planar 5V | Voltage | Nominal | 4.90 | V | 'OK' -6 | Planar 12V | Voltage | Nominal | 11.99 | V | 'OK' -7 | Planar VBAT | Voltage | Nominal | 2.95 | V | 'OK' -8 | Fan 1A Tach | Fan | Nominal | 3132.00 | RPM | 'OK' -9 | Fan 1B Tach | Fan | Nominal | 2150.00 | RPM | 'OK' -10 | Fan 2A Tach | Fan | Nominal | 2494.00 | RPM | 'OK' -11 | Fan 2B Tach | Fan | Nominal | 1825.00 | RPM | 'OK' -12 | Fan 3A Tach | Fan | Nominal | 3538.00 | RPM | 'OK' -13 | Fan 3B Tach | Fan | Nominal | 2625.00 | RPM | 'OK' -14 | Fan 1 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' -15 | Fan 2 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' -... -``` - -## Debugging - -You can run the plugin by hand: - -```sh -# become user netdata -sudo su -s /bin/sh netdata - -# run the plugin in debug mode -/usr/libexec/netdata/plugins.d/freeipmi.plugin 5 debug -``` - -You will get verbose output on what the plugin does. - -## kipmi0 CPU usage - -There have been reports that kipmi is showing increased CPU when the IPMI is queried. To lower the CPU consumption of -the system you can issue this command: - -```sh -echo 10 > /sys/module/ipmi_si/parameters/kipmid_max_busy_us -``` - -You can also permanently set the above setting by creating the file `/etc/modprobe.d/ipmi.conf` with this content: - -```sh -# prevent kipmi from consuming 100% CPU -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). - -If you need to disable IPMI for Netdata, edit `/etc/netdata/netdata.conf` and set: - -``` -[plugins] - freeipmi = no -``` +integrations/intelligent_platform_management_interface_ipmi.md
\ No newline at end of file diff --git a/collectors/freeipmi.plugin/freeipmi_plugin.c b/collectors/freeipmi.plugin/freeipmi_plugin.c index 56a1c4998..63147d621 100644 --- a/collectors/freeipmi.plugin/freeipmi_plugin.c +++ b/collectors/freeipmi.plugin/freeipmi_plugin.c @@ -1146,7 +1146,7 @@ int netdata_ipmi_detect_speed_secs(struct ipmi_monitoring_ipmi_config *ipmi_conf successful++; if(unlikely(state->debug)) - fprintf(stderr, "%s: %s data collection speed was %llu usec\n", + fprintf(stderr, "%s: %s data collection speed was %"PRIu64" usec\n", program_name, netdata_collect_type_to_string(type), end - start); // add it to our total @@ -1307,7 +1307,7 @@ static size_t send_ipmi_sensor_metrics_to_netdata(struct netdata_ipmi_state *sta if(likely(sn->do_metric)) { if(unlikely(!is_sensor_updated(sn->last_collected_metric_ut, state->updates.now_ut, state->sensors.freq_ut))) { if(unlikely(state->debug)) - fprintf(stderr, "%s: %s() sensor '%s' metric is not UPDATED (last updated %llu, now %llu, freq %llu\n", + fprintf(stderr, "%s: %s() sensor '%s' metric is not UPDATED (last updated %"PRIu64", now %"PRIu64", freq %"PRIu64"\n", program_name, __FUNCTION__, sn->sensor_name, sn->last_collected_metric_ut, state->updates.now_ut, state->sensors.freq_ut); } else { @@ -1360,7 +1360,7 @@ static size_t send_ipmi_sensor_metrics_to_netdata(struct netdata_ipmi_state *sta if(likely(sn->do_state)) { if(unlikely(!is_sensor_updated(sn->last_collected_state_ut, state->updates.now_ut, state->sensors.freq_ut))) { if (unlikely(state->debug)) - fprintf(stderr, "%s: %s() sensor '%s' state is not UPDATED (last updated %llu, now %llu, freq %llu\n", + fprintf(stderr, "%s: %s() sensor '%s' state is not UPDATED (last updated %"PRIu64", now %"PRIu64", freq %"PRIu64"\n", program_name, __FUNCTION__, sn->sensor_name, sn->last_collected_state_ut, state->updates.now_ut, state->sensors.freq_ut); } else { @@ -1450,6 +1450,8 @@ int main (int argc, char **argv) { error_log_errors_per_period = 100; error_log_throttle_period = 3600; + log_set_global_severity_for_external_plugins(); + // initialize the threads netdata_threads_init_for_external_plugins(0); // set the default threads stack size here @@ -1870,7 +1872,7 @@ int main (int argc, char **argv) { send_ipmi_sel_metrics_to_netdata(&state); if(unlikely(debug)) - fprintf(stderr, "%s: iteration %zu, dt %llu usec, sensors ever collected %zu, sensors last collected %zu \n" + fprintf(stderr, "%s: iteration %zu, dt %"PRIu64" usec, sensors ever collected %zu, sensors last collected %zu \n" , program_name , iteration , dt diff --git a/collectors/freeipmi.plugin/integrations/intelligent_platform_management_interface_ipmi.md b/collectors/freeipmi.plugin/integrations/intelligent_platform_management_interface_ipmi.md new file mode 100644 index 000000000..6d894667b --- /dev/null +++ b/collectors/freeipmi.plugin/integrations/intelligent_platform_management_interface_ipmi.md @@ -0,0 +1,274 @@ +<!--startmeta +custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/freeipmi.plugin/README.md" +meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/freeipmi.plugin/metadata.yaml" +sidebar_label: "Intelligent Platform Management Interface (IPMI)" +learn_status: "Published" +learn_rel_path: "Data Collection/Hardware Devices and Sensors" +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" +endmeta--> + +# Intelligent Platform Management Interface (IPMI) + + +<img src="https://netdata.cloud/img/netdata.png" width="150"/> + + +Plugin: freeipmi.plugin +Module: freeipmi + +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> + +## Overview + +"Monitor enterprise server sensor readings, event log entries, and hardware statuses to ensure reliable server operations." + + +The plugin uses open source library IPMImonitoring to communicate with sensors. + + +This collector is supported on all platforms. + +This collector supports collecting metrics from multiple instances of this integration, including remote instances. + +The plugin needs setuid. + +### Default Behavior + +#### Auto-Detection + +This integration doesn't support auto-detection. + +#### Limits + +The default configuration for this integration does not impose any limits on data collection. + +#### Performance Impact + +Linux kernel module for IPMI can create big overhead. + + +## Metrics + +Metrics grouped by *scope*. + +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. + +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. + + +### Per Intelligent Platform Management Interface (IPMI) instance + +These metrics refer to the entire monitored application. + +This scope has no labels. + +Metrics: + +| Metric | Dimensions | Unit | +|:------|:----------|:----| +| ipmi.sel | events | events | + +### Per sensor + + + +Labels: + +| Label | Description | +|:-----------|:----------------| +| sensor | The sensor name | +| type | One of 45 recognized sensor types (Battery, Voltage...) | +| component | One of 25 recognized components (Processor, Peripheral). | + +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 | % | + + + +## Alerts + + +The following alerts are available: + +| Alert name | On metric | Description | +|:------------|:----------|:------------| +| [ ipmi_sensor_state ](https://github.com/netdata/netdata/blob/master/health/health.d/ipmi.conf) | ipmi.sensor_state | IPMI sensor ${label:sensor} (${label:component}) state | + + +## Setup + +### Prerequisites + +#### Install freeipmi.plugin + +When using our official DEB/RPM packages, the FreeIPMI plugin is included in a separate package named `netdata-plugin-freeipmi` which needs to be manually installed using your system package manager. It is not 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. + + +#### Preliminary actions + +If you have not previously used IPMI on your system, you will probably need to run the `ipmimonitoring` command as root +to initialize IPMI settings so that the Netdata plugin works correctly. It should return information about available sensors on the system. + + + +### Configuration + +#### File + +The configuration file name for this integration is `netdata.conf`. +Configuration for this specific integration is located in the `[plugin:freeipmi]` section within that file. + +The file format is a modified INI syntax. The general structure is: + +```ini +[section1] + option1 = some value + option2 = some other value + +[section2] + option3 = some third value +``` +You can edit the configuration file using the `edit-config` script from the +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory). + +```bash +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata +sudo ./edit-config netdata.conf +``` +#### Options + +The configuration is set using command line options: + +``` +# netdata.conf +[plugin:freeipmi] + command options = opt1 opt2 ... optN +``` + +To display a help message listing the available command line options: + +```bash +./usr/libexec/netdata/plugins.d/freeipmi.plugin --help +``` + + +<details><summary>Command options</summary> + +| Name | Description | Default | Required | +|:----|:-----------|:-------|:--------:| +| SECONDS | Data collection frequency. | | False | +| debug | Enable verbose output. | disabled | False | +| no-sel | Disable System Event Log (SEL) collection. | disabled | False | +| reread-sdr-cache | Re-read SDR cache on every iteration. | disabled | False | +| interpret-oem-data | Attempt to parse OEM data. | disabled | False | +| assume-system-event-record | treat illegal SEL events records as normal. | disabled | False | +| ignore-non-interpretable-sensors | Do not read sensors that cannot be interpreted. | disabled | False | +| bridge-sensors | Bridge sensors not owned by the BMC. | disabled | False | +| shared-sensors | Enable shared sensors if found. | disabled | False | +| no-discrete-reading | Do not read sensors if their event/reading type code is invalid. | enabled | False | +| ignore-scanning-disabled | Ignore the scanning bit and read sensors no matter what. | disabled | False | +| assume-bmc-owner | Assume the BMC is the sensor owner no matter what (usually bridging is required too). | disabled | False | +| hostname HOST | Remote IPMI hostname or IP address. | local | False | +| username USER | Username that will be used when connecting to the remote host. | | False | +| password PASS | Password that will be used when connecting to the remote host. | | False | +| noauthcodecheck / no-auth-code-check | Don't check the authentication codes returned. | | False | +| 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. | | False | +| sdr-cache-dir PATH | SDR cache files directory. | /tmp | False | +| sensor-config-file FILE | Sensors configuration filename. | system default | False | +| sel-config-file FILE | SEL configuration filename. | system default | False | +| ignore N1,N2,N3,... | Sensor IDs to ignore. | | False | +| ignore-status N1,N2,N3,... | Sensor IDs to ignore status (nominal/warning/critical). | | False | +| -v | Print version and exit. | | False | +| --help | Print usage message and exit. | | False | + +</details> + +#### Examples + +##### Decrease data collection frequency + +Basic example decreasing data collection frequency. 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. + +```yaml +[plugin:freeipmi] + update every = 10 + +``` +##### Disable SEL collection + +Append to `command options =` the options you need. + +<details><summary>Config</summary> + +```yaml +[plugin:freeipmi] + command options = no-sel + +``` +</details> + +##### Ignore 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`). + +To find the IDs to ignore, run the command `ipmimonitoring`. The first column is the wanted ID: + +ID | Name | Type | State | Reading | Units | Event +1 | Ambient Temp | Temperature | Nominal | 26.00 | C | 'OK' +2 | Altitude | Other Units Based Sensor | Nominal | 480.00 | ft | 'OK' +3 | Avg Power | Current | Nominal | 100.00 | W | 'OK' +4 | Planar 3.3V | Voltage | Nominal | 3.29 | V | 'OK' +5 | Planar 5V | Voltage | Nominal | 4.90 | V | 'OK' +6 | Planar 12V | Voltage | Nominal | 11.99 | V | 'OK' +7 | Planar VBAT | Voltage | Nominal | 2.95 | V | 'OK' +8 | Fan 1A Tach | Fan | Nominal | 3132.00 | RPM | 'OK' +9 | Fan 1B Tach | Fan | Nominal | 2150.00 | RPM | 'OK' +10 | Fan 2A Tach | Fan | Nominal | 2494.00 | RPM | 'OK' +11 | Fan 2B Tach | Fan | Nominal | 1825.00 | RPM | 'OK' +12 | Fan 3A Tach | Fan | Nominal | 3538.00 | RPM | 'OK' +13 | Fan 3B Tach | Fan | Nominal | 2625.00 | RPM | 'OK' +14 | Fan 1 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' +15 | Fan 2 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' +... + +`freeipmi.plugin` supports the option `ignore` that accepts a comma separated list of sensor IDs to ignore. To configure it set on `netdata.conf`: + + +<details><summary>Config</summary> + +```yaml +[plugin:freeipmi] + command options = ignore 1,2,3,4,... + +``` +</details> + + + +## Troubleshooting + +### Debug Mode + + + +### kimpi0 CPU usage + + + + diff --git a/collectors/freeipmi.plugin/metadata.yaml b/collectors/freeipmi.plugin/metadata.yaml index 9540410bf..f8c75c2cb 100644 --- a/collectors/freeipmi.plugin/metadata.yaml +++ b/collectors/freeipmi.plugin/metadata.yaml @@ -2,7 +2,7 @@ plugin_name: freeipmi.plugin modules: - meta: plugin_name: freeipmi.plugin - module_name: sensors + module_name: freeipmi monitored_instance: name: Intelligent Platform Management Interface (IPMI) link: "https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface" @@ -42,34 +42,225 @@ modules: setup: prerequisites: list: - - title: Preliminary actions + - title: Install freeipmi.plugin description: | - If you have not previously used IPMI on your system, you will probably need to run the ipmimonitoring command as root to initialize IPMI settings so that the Netdata plugin works correctly. It should return information about available sensors on the system. + When using our official DEB/RPM packages, the FreeIPMI plugin is included in a separate package named `netdata-plugin-freeipmi` which needs to be manually installed using your system package manager. It is not 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. - 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 should find the file and link it to the standard pkg-config directory. Usually, running sudo ln -s /usr/lib/$(uname -m)-linux-gnu/pkgconfig/libipmimonitoring.pc/libipmimonitoring.pc /usr/lib/pkgconfig/libipmimonitoring.pc resolves this issue. + 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. + - title: Preliminary actions + description: | + If you have not previously used IPMI on your system, you will probably need to run the `ipmimonitoring` command as root + to initialize IPMI settings so that the Netdata plugin works correctly. It should return information about available sensors on the system. configuration: file: name: "netdata.conf" - section_name: '[plugin:freeipmi]' - description: "This is netdata main configuration file" + section_name: "[plugin:freeipmi]" options: - description: "This tool receives command line options that are visible when user run: `./usr/libexec/netdata/plugins.d/freeipmi.plugin --help`" + description: | + The configuration is set using command line options: + + ``` + # netdata.conf + [plugin:freeipmi] + command options = opt1 opt2 ... optN + ``` + + To display a help message listing the available command line options: + + ```bash + ./usr/libexec/netdata/plugins.d/freeipmi.plugin --help + ``` folding: - title: "Config options" + title: "Command options" enabled: true list: - - name: command options - description: Variable used to pass arguments for the plugin. - default_value: 1 + - name: SECONDS + description: Data collection frequency. + default_value: "" + required: false + - name: debug + description: Enable verbose output. + default_value: disabled + required: false + - name: no-sel + description: Disable System Event Log (SEL) collection. + default_value: disabled + required: false + - name: reread-sdr-cache + description: Re-read SDR cache on every iteration. + default_value: disabled + required: false + - name: interpret-oem-data + description: Attempt to parse OEM data. + default_value: disabled + required: false + - name: assume-system-event-record + description: treat illegal SEL events records as normal. + default_value: disabled + required: false + - name: ignore-non-interpretable-sensors + description: Do not read sensors that cannot be interpreted. + default_value: disabled + required: false + - name: bridge-sensors + description: Bridge sensors not owned by the BMC. + default_value: disabled + required: false + - name: shared-sensors + description: Enable shared sensors if found. + default_value: disabled + required: false + - name: no-discrete-reading + description: Do not read sensors if their event/reading type code is invalid. + default_value: enabled + required: false + - name: ignore-scanning-disabled + description: Ignore the scanning bit and read sensors no matter what. + default_value: disabled + required: false + - name: assume-bmc-owner + description: Assume the BMC is the sensor owner no matter what (usually bridging is required too). + default_value: disabled + required: false + - name: hostname HOST + description: Remote IPMI hostname or IP address. + default_value: local + required: false + - name: username USER + description: Username that will be used when connecting to the remote host. + default_value: "" + required: false + - name: password PASS + description: Password that will be used when connecting to the remote host. + default_value: "" + required: false + - name: noauthcodecheck / no-auth-code-check + description: Don't check the authentication codes returned. + default_value: "" + required: false + - name: driver-type IPMIDRIVER + description: 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. + default_value: "" + required: false + - name: sdr-cache-dir PATH + description: SDR cache files directory. + default_value: /tmp + required: false + - name: sensor-config-file FILE + description: Sensors configuration filename. + default_value: system default + required: false + - name: sel-config-file FILE + description: SEL configuration filename. + default_value: system default + required: false + - name: ignore N1,N2,N3,... + description: Sensor IDs to ignore. + default_value: "" + required: false + - name: ignore-status N1,N2,N3,... + description: Sensor IDs to ignore status (nominal/warning/critical). + default_value: "" + required: false + - name: -v + description: Print version and exit. + default_value: "" + required: false + - name: --help + description: Print usage message and exit. + default_value: "" required: false examples: folding: enabled: true - title: "" - list: [] + title: "Config" + list: + - name: Decrease data collection frequency + description: Basic example decreasing data collection frequency. 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. + config: | + [plugin:freeipmi] + update every = 10 + folding: + enabled: false + - name: Disable SEL collection + description: Append to `command options =` the options you need. + config: | + [plugin:freeipmi] + command options = no-sel + - name: Ignore specific sensors + description: | + 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`). + + To find the IDs to ignore, run the command `ipmimonitoring`. The first column is the wanted ID: + + ID | Name | Type | State | Reading | Units | Event + 1 | Ambient Temp | Temperature | Nominal | 26.00 | C | 'OK' + 2 | Altitude | Other Units Based Sensor | Nominal | 480.00 | ft | 'OK' + 3 | Avg Power | Current | Nominal | 100.00 | W | 'OK' + 4 | Planar 3.3V | Voltage | Nominal | 3.29 | V | 'OK' + 5 | Planar 5V | Voltage | Nominal | 4.90 | V | 'OK' + 6 | Planar 12V | Voltage | Nominal | 11.99 | V | 'OK' + 7 | Planar VBAT | Voltage | Nominal | 2.95 | V | 'OK' + 8 | Fan 1A Tach | Fan | Nominal | 3132.00 | RPM | 'OK' + 9 | Fan 1B Tach | Fan | Nominal | 2150.00 | RPM | 'OK' + 10 | Fan 2A Tach | Fan | Nominal | 2494.00 | RPM | 'OK' + 11 | Fan 2B Tach | Fan | Nominal | 1825.00 | RPM | 'OK' + 12 | Fan 3A Tach | Fan | Nominal | 3538.00 | RPM | 'OK' + 13 | Fan 3B Tach | Fan | Nominal | 2625.00 | RPM | 'OK' + 14 | Fan 1 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' + 15 | Fan 2 | Entity Presence | Nominal | N/A | N/A | 'Entity Present' + ... + + `freeipmi.plugin` supports the option `ignore` that accepts a comma separated list of sensor IDs to ignore. To configure it set on `netdata.conf`: + config: | + [plugin:freeipmi] + command options = ignore 1,2,3,4,... troubleshooting: problems: - list: [] + list: + - name: Debug Mode + description: | + You can run `freeipmi.plugin` with the debug option enabled, to troubleshoot issues with it. The output should give you clues as to why the collector isn't working. + + - Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`. + + ```bash + cd /usr/libexec/netdata/plugins.d/ + ``` + + - Switch to the `netdata` user. + + ```bash + sudo -u netdata -s + ``` + + - Run the `freeipmi.plugin` in debug mode: + + ```bash + ./freeipmi.plugin 5 debug + ``` + - name: kimpi0 CPU usage + description: | + There have been reports that kipmi is showing increased CPU when the IPMI is queried. To lower the CPU consumption of the system you can issue this command: + + ```sh + echo 10 > /sys/module/ipmi_si/parameters/kipmid_max_busy_us + ``` + + You can also permanently set the above setting by creating the file `/etc/modprobe.d/ipmi.conf` with this content: + + ```sh + # prevent kipmi from consuming 100% CPU + 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). alerts: - name: ipmi_sensor_state link: https://github.com/netdata/netdata/blob/master/health/health.d/ipmi.conf @@ -79,9 +270,20 @@ modules: folding: title: Metrics enabled: false - description: "" + description: | + 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. availability: [] scopes: + - name: global + description: These metrics refer to the entire monitored application. + labels: [] + metrics: + - name: ipmi.sel + description: IPMI Events + unit: "events" + chart_type: area + dimensions: + - name: events - name: sensor description: "" labels: @@ -92,12 +294,6 @@ modules: - name: component description: One of 25 recognized components (Processor, Peripheral). metrics: - - name: ipmi.sel - description: IPMI Events - unit: "events" - chart_type: area - dimensions: - - name: events - name: ipmi.sensor_state description: IPMI Sensors State unit: "state" |