From 557f2c072bbe39bb2898d1b7992a1d212b991f3c Mon Sep 17 00:00:00 2001 From: Conrad Hoffmann Date: Fri, 18 Oct 2024 10:03:21 +0200 Subject: [PATCH] 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 | 65 +++++++++++++------------------------------ docs/configuration.md | 25 +++++++++-------- docs/privileges.md | 31 +++++++++++++++++++++ ipmi_local.yml | 4 ++- ipmi_local_sudo.yml | 32 +++++++++++++++++++++ ipmi_remote.yml | 21 -------------- 6 files changed, 99 insertions(+), 79 deletions(-) create mode 100644 docs/privileges.md create mode 100644 ipmi_local_sudo.yml diff --git a/README.md b/README.md index 6f6a6fc..24a6d67 100644 --- a/README.md +++ b/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 +When running a container image, make sure to: -If you are running the exporter as unprivileged user, but need to execute the -FreeIPMI tools as root, you can do the following: + - set `config.file` to where the config file is mounted + - expose the default port (9290) or set `web.listen-address` accordingly - 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`. +**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. diff --git a/docs/configuration.md b/docs/configuration.md index cc7cf9c..b8d4f0d 100644 --- a/docs/configuration.md +++ b/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. +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 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. +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: diff --git a/docs/privileges.md b/docs/privileges.md new file mode 100644 index 0000000..c8c1035 --- /dev/null +++ b/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. diff --git a/ipmi_local.yml b/ipmi_local.yml index af2dc71..e30cee8 100644 --- a/ipmi_local.yml +++ b/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 diff --git a/ipmi_local_sudo.yml b/ipmi_local_sudo.yml new file mode 100644 index 0000000..9f28818 --- /dev/null +++ b/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" diff --git a/ipmi_remote.yml b/ipmi_remote.yml index 94a7ffc..23dbde2 100644 --- a/ipmi_remote.yml +++ b/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"