From 18bffd7c144233cebf669b0e52389220aece4ea5 Mon Sep 17 00:00:00 2001
From: Holger Obermaier <40787752+ho-ob@users.noreply.github.com>
Date: Mon, 21 Nov 2022 13:58:30 +0100
Subject: [PATCH] Add documentaion for IPMI receiver

---
 receivers/ipmiReceiver.go | 36 ++++++++++++++---------------
 receivers/ipmiReceiver.md | 48 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 18 deletions(-)
 create mode 100644 receivers/ipmiReceiver.md

diff --git a/receivers/ipmiReceiver.go b/receivers/ipmiReceiver.go
index acae2d7..5c5cb08 100644
--- a/receivers/ipmiReceiver.go
+++ b/receivers/ipmiReceiver.go
@@ -19,16 +19,16 @@ import (
 type IPMIReceiverClientConfig struct {
 
 	// Hostname the IPMI service belongs to
-	Protocol         string
-	DriverType       string
-	Fanout           int
-	NumHosts         int
-	IPMIHosts        string
-	IPMI2HostMapping map[string]string
-	Username         string
-	Password         string
-	CLIOptions       []string
-	isExcluded       map[string]bool
+	Protocol         string            // Protocol / tool to use for IPMI sensor reading
+	DriverType       string            // Out of band IPMI driver
+	Fanout           int               // Maximum number of simultaneous IPMI connections
+	NumHosts         int               // Number of remote IPMI devices with the same configuration
+	IPMIHosts        string            // List of remote IPMI devices to communicate with
+	IPMI2HostMapping map[string]string // Mapping between IPMI device name and host name
+	Username         string            // User name to authenticate with
+	Password         string            // Password to use for authentication
+	CLIOptions       []string          // Additional command line options for ipmi-sensors
+	isExcluded       map[string]bool   // is metric excluded
 }
 
 type IPMIReceiver struct {
@@ -178,7 +178,6 @@ func (r *IPMIReceiver) doReadMetric() {
 				if err == nil {
 					r.sink <- y
 				}
-
 			}
 
 			// Wait for command end
@@ -249,29 +248,30 @@ func NewIPMIReceiver(name string, config json.RawMessage) (Receiver, error) {
 	configJSON := struct {
 		Type string `json:"type"`
 
-		// Maximum number of simultaneous IPMI connections (default: 64)
-		Fanout int `json:"fanout,omitempty"`
-		// Out of band IPMI driver (default: LAN_2_0)
-		DriverType string `json:"driver_type,omitempty"`
-
 		// How often the IPMI sensor metrics should be read and send to the sink (default: 30 s)
 		IntervalString string `json:"interval,omitempty"`
 
+		// Maximum number of simultaneous IPMI connections (default: 64)
+		Fanout int `json:"fanout,omitempty"`
+
+		// Out of band IPMI driver (default: LAN_2_0)
+		DriverType string `json:"driver_type,omitempty"`
+
 		// Default client username, password and endpoint
 		Username *string `json:"username"` // User name to authenticate with
 		Password *string `json:"password"` // Password to use for authentication
-		Endpoint *string `json:"endpoint"` // URL of the IPMI service
+		Endpoint *string `json:"endpoint"` // URL of the IPMI device
 
 		// Globally excluded metrics
 		ExcludeMetrics []string `json:"exclude_metrics,omitempty"`
 
 		ClientConfigs []struct {
-			Endpoint   *string  `json:"endpoint"`              // URL of the IPMI service
 			Fanout     int      `json:"fanout,omitempty"`      // Maximum number of simultaneous IPMI connections (default: 64)
 			DriverType string   `json:"driver_type,omitempty"` // Out of band IPMI driver (default: LAN_2_0)
 			HostList   []string `json:"host_list"`             // List of hosts with the same client configuration
 			Username   *string  `json:"username"`              // User name to authenticate with
 			Password   *string  `json:"password"`              // Password to use for authentication
+			Endpoint   *string  `json:"endpoint"`              // URL of the IPMI service
 
 			// Per client excluded metrics
 			ExcludeMetrics []string `json:"exclude_metrics,omitempty"`
diff --git a/receivers/ipmiReceiver.md b/receivers/ipmiReceiver.md
new file mode 100644
index 0000000..a82211e
--- /dev/null
+++ b/receivers/ipmiReceiver.md
@@ -0,0 +1,48 @@
+## IPMI Receiver
+
+The IPMI Receiver uses `ipmi-sensors` from the [FreeIPMI](https://www.gnu.org/software/freeipmi/) project to read IPMI sensor readings and sensor data repository (SDR) information. The available metrics depend on the sensors provided by the hardware vendor but typically contain temperature, fan speed, voltage and power metrics.
+
+### Configuration structure
+
+```json
+{
+    "<IPMI receiver name>": {
+        "type": "ipmi",
+        "interval": "30s",
+        "fanout": 256,
+        "username": "<Username>",
+        "password": "<Password>",
+        "endpoint": "ipmi-sensors://%h-p",
+        "exclude_metrics": [ "fan_speed", "voltage" ],
+        "client_config": [
+            {
+                "host_list": ["n1", "n2", "n3", "n4" ]
+            },
+            {
+                "host_list": [ "n5", "n6" ],
+                "driver_type": "LAN",
+                "cli_options": [ "--workaround-flags=..." ],
+                "password": "<Password 2>"
+            }
+        ]
+    }
+}
+```
+
+Global settings:
+
+- `interval`: How often the IPMI sensor metrics should be read and send to the sink (default: 30 s)
+
+Global and per IPMI device settings (per IPMI device settings overwrite the global settings):
+
+- `exclude_metrics`: list of excluded metrics e.g. fan_speed, power, temperature, utilization, voltage
+- `fanout`: Maximum number of simultaneous IPMI connections (default: 64)
+- `driver_type`: Out of band IPMI driver (default: LAN_2_0)
+- `username`: User name to authenticate with
+- `password`: Password to use for authentication
+- `endpoint`: URL of the IPMI device (placeholder `%h` gets replaced by the hostname)
+
+Per IPMI device settings:
+
+- `host_list`: List of hosts with the same client configuration
+- `cli_options`: Additional command line options for ipmi-sensors