Refactor and improve documentation

* Streamline README
* Link to container imgages
* Move privileges part to separate doc
* Use absolute paths for `sudo` examples
* Emphasize `sudo` only being needed for local metrics

README.md

@@ -31,6 +31,12 @@ For Kubernets, you can use the community-maintained [Helm chart][helm].
 
 [helm]: https://github.com/prometheus-community/helm-charts/tree/main/charts/prometheus-ipmi-exporter "IPMI exporter Helm chart in the helm-charts Github repo"
 
+Pre-built container images are available on [dockerhub][dockerhub] and
+[quay.io][quay.io].
+
+[dockerhub]: https://hub.docker.com/r/prometheuscommunity/ipmi-exporter
+[quay.io]: https://quay.io/repository/prometheuscommunity/ipmi-exporter
+
 ### Building from source
 
 You need a Go development environment. Then, simply run `make` to build the
@@ -43,23 +49,16 @@ This uses the common prometheus tooling to build and run some tests.
 Alternatively, you can use the standard Go tooling, which will install the
 executable in `$GOPATH/bin`:
 
-    go get github.com/prometheus-community/ipmi_exporter
+    go install github.com/prometheus-community/ipmi_exporter@latest
 
-### Building a Docker container
+### Building a container image
 
-You can build a Docker container with the included `docker` make target:
+You can build a container image with the included `docker` make target:
 
     make promu
     promu crossbuild -p linux/amd64 -p linux/arm64
     make docker
 
-This will not even require Go tooling on the host. See the included [docker
-compose example](docker-compose.yml) for how to use the resulting container.
-
-### Building a RPM Package
-
-See [how to build a RPM package](contrib/rpm/README.md).
-
 ## Running
 
 A minimal invocation looks like this:
@@ -86,44 +85,12 @@ installed:
  - `ipmi-sel`
  - `ipmi-chassis`
 
-### Running as unprivileged user
-
-If you are running the exporter as unprivileged user, but need to execute the
-FreeIPMI tools as root, you can do the following:
-
-  1. Add sudoers files to permit the following commands
-     ```
-     ipmi-exporter ALL = NOPASSWD: /usr/sbin/ipmimonitoring,\
-                                   /usr/sbin/ipmi-sensors,\
-                                   /usr/sbin/ipmi-dcmi,\
-                                   /usr/sbin/ipmi-raw,\
-                                   /usr/sbin/bmc-info,\
-                                   /usr/sbin/ipmi-chassis,\
-                                   /usr/sbin/ipmi-sel
-     ```
-  2. In your module config, override the collector command with `sudo` for
-     every collector you are using and add the actual command as custom
-     argument. Example for the "ipmi" collector:
-     ```yaml
-     collector_cmd:
-       ipmi: sudo
-     custom_args:
-       ipmi:
-       - "ipmimonitoring"
-     ```
-     See the last module in the [example config](ipmi_remote.yml).
-
-### Running in Docker
-
-**NOTE:** you should only use Docker for remote metrics.
-
-See [Building a Docker container](#building-a-docker-container) and the example
-`docker-compose.yml`. Edit the `ipmi_remote.yml` file to configure IPMI
-credentials, then run with:
-
-    sudo docker-compose up -d
-
-By default, the server will bind on `0.0.0.0:9290`.
+When running a container image, make sure to:
+
+ - set `config.file` to where the config file is mounted
+ - expose the default port (9290) or set `web.listen-address` accordingly
+
+**NOTE:** you should only use containers for collecting remote metrics.
 
 ## Configuration
 
@@ -145,3 +112,9 @@ using the `--web.config.file` parameter. The format of the file is described
 
 For a description of the metrics that this exporter provides, see the
 [metrics](docs/metrics.md) document.
+
+## Privileges
+
+Collecting host-local IPMI metrics requires root privileges. See
+[privileges](docs/privileges.md) document for how to avoid running the exporter
+as root.

docs/configuration.md

@@ -1,17 +1,20 @@
 # Configuration
 
 Simply scraping the standard `/metrics` endpoint will make the exporter emit
-local IPMI metrics. No special configuration is required.
-
-For remote metrics, the general configuration pattern is similar to that of the
-[blackbox exporter](https://github.com/prometheus/blackbox_exporter), i.e.
-Prometheus scrapes a small number (possibly one) of IPMI exporters with a
-`target` and `module` URL parameter to tell the exporter which IPMI device it
-should use to retrieve the IPMI metrics. We offer this approach as IPMI devices
-often provide useful information even while the supervised host is turned off.
-If you are running the exporter on a separate host anyway, it makes more sense
-to have only a few of them, each probing many (possibly thousands of) IPMI
-devices, rather than one exporter per IPMI device.
+local IPMI metrics. If the exporter is running with sufficient privileges, no
+special configuration is required. See the [privileges document](privileges.md)
+for more details.
+
+For remote metrics, the general configuration pattern is that of a
+[multi-target exporter][multi-target]. Please read that guide to get the general
+idea about this approach.
+
+[multi-target]: https://prometheus.io/docs/guides/multi-target-exporter/ "Understanding and using the multi-target exporter pattern - Prometheus docs"
+
+We offer this approach as IPMI devices often provide useful information even
+while the supervised host is turned off. Also, you can have a single exporter
+instance probing many (possibly thousands of) IPMI devices, rather than one
+exporter per IPMI device.
 
 **NOTE:** If you are using remote metrics, but still want to get the local
 process metrics from the instance, you must use a `default` module with an
@@ -83,7 +86,7 @@ Create a YAML file that contains a list of targets, e.g.:
     job: ipmi_exporter
 ```
 
-This file needs to be stored on the Prometheus server host.  Assuming that this
+This file needs to be stored on the Prometheus server host. Assuming that this
 file is called `/srv/ipmi_exporter/targets.yml`, and the IPMI exporter is
 running on a host that has the DNS name `ipmi-exporter.internal.example.com`,
 add the following to your Prometheus config:

docs/privileges.md

@@ -0,0 +1,31 @@
+# Privileges
+
+If you are running the exporter as unprivileged user, but need to execute the
+FreeIPMI tools as root (as is likely necessary to access the local IPMI
+interface), you can do the following:
+
+**NOTE:** Make sure to adapt all absolute paths to match your distro!
+
+  1. Add sudoers files to permit the following commands
+     ```
+     ipmi-exporter ALL = NOPASSWD: /usr/sbin/ipmimonitoring,\
+                                   /usr/sbin/ipmi-sensors,\
+                                   /usr/sbin/ipmi-dcmi,\
+                                   /usr/sbin/ipmi-raw,\
+                                   /usr/sbin/bmc-info,\
+                                   /usr/sbin/ipmi-chassis,\
+                                   /usr/sbin/ipmi-sel
+     ```
+  2. In your module config, override the collector command with `sudo` for
+     every collector you are using and add the actual command as custom
+     argument. Example for the "ipmi" collector:
+     ```yaml
+     collector_cmd:
+       ipmi: /usr/bin/sudo
+     custom_args:
+       ipmi:
+       - "/usr/sbin/ipmimonitoring"
+     ```
+     See also the [sudo example config](../ipmi_local_sudo.yml).
+
+Note that no elevated privileges are necessary for getting remote metrics.

ipmi_local.yml

@@ -1,7 +1,9 @@
 # Configuration file for ipmi_exporter
 
 # This is an example config for scraping the local host.
-# In most cases, this should work without using a config file at all.
+# In most cases, this should work without using a config file at all, but here
+# are some examples of things that can be customized. If you require privilege
+# elevation to get the local metrics, see the `ipmi_local_sudo.yml` example.
 modules:
   default:
     # Available collectors are bmc, bmc-watchdog, ipmi, chassis, dcmi, sel, sel-events and sm-lan-mode

ipmi_local_sudo.yml

@@ -0,0 +1,32 @@
+# Configuration file for ipmi_exporter
+
+# This is an example config for scraping the local host, using `sudo` to
+# elevate privileges for access to the IPMI interface.
+modules:
+  default:
+    # Available collectors are bmc, bmc-watchdog, ipmi, chassis, dcmi, sel, sel-events and sm-lan-mode
+    collectors:
+      - ipmi
+      - sel
+    # Got any sensors you don't care about? Add them here.
+    exclude_sensor_ids:
+      - 2
+      - 29
+      - 32
+    # Define custom metrics for SEL entries
+    sel_events:
+      - name: correctable_memory_error
+        regex: Correctable memory error.*
+    # USING ANY OF THE BELOW VOIDS YOUR WARRANTY! YOU MAY GET BITTEN BY SHARKS!
+    # You can override the command to be executed for a collector. Paired with
+    # custom_args, this can be used to e.g. execute the IPMI tools with sudo.
+    # Must be added for every enabled collector. Adapt the path to match your
+    # distro, and read `docs/privileges.md`!
+    collector_cmd:
+      ipmi: /usr/bin/sudo
+      sel: /usr/bin/sudo
+    custom_args:
+      ipmi:
+      - "/usr/sbin/ipmimonitoring"
+      sel:
+      - "/usr/sbin/ipmi-sel"

ipmi_remote.yml

@@ -4,7 +4,6 @@
 # Information required to access remote IPMI interfaces can be supplied in the
 # 'modules' section. A scrape can request the usage of a given config by
 # setting the `module` URL parameter.
-
 modules:
   default:
     # These settings are used if no module is specified, the
@@ -66,23 +65,3 @@ modules:
     custom_args:
       ipmi:
       - "--bridge-sensors"
-  advanced:
-    # Use these settings when scraped with module=advanced.
-    user: "some_user"
-    pass: "secret_pw"
-    privilege: "admin"
-    driver: "LAN"
-    collectors:
-    - ipmi
-    - sel
-    # USING ANY OF THE BELOW VOIDS YOUR WARRANTY! YOU MAY GET BITTEN BY SHARKS!
-    # You can override the command to be executed for a collector. Paired with
-    # custom_args, this can be used to e.g. execute the IPMI tools with sudo:
-    collector_cmd:
-      ipmi: sudo
-      sel: sudo
-    custom_args:
-      ipmi:
-      - "ipmimonitoring"
-      sel:
-      - "ipmi-sel"