Homelab on

UPS monitoring with Grafana

Fri, 30 Aug 2024 00:00:00 +0000

UPS Monitoring

First off, you have connected the UPS to a free USB port and it shows up using lsusb thus:

1
2


$  lsusb
Bus 001 Device 004: ID 051d:0002 American Power Conversion Uninterruptible Power Supply

Install the required APC UPS daemon and PHP packages with:

apt install apcupsd php -y

Once installed stop the apcupsd service if it started automatically with

systemctl stop apcupsd

You’ll next need to edit the configuration file for the service which lives at /etc/apcupsd/apcupsd.conf . If you’d like enter a UPSNAME that makes sense. Then the default version of this file on my system had a line that looked like DEVICE /tty/xxx0, comment out or delete this line and restart the service with:

1
2


systemctl start apcupsd
systemctl status apcupsd

If everything looks good in status you should now be able to run:

1
2
3
4
5
6
7


$  apcaccess
APC      : 001,036,0866
DATE     : 2024-08-24 18:46:26 +0200
HOSTNAME : pinet
VERSION  : 3.14.14 (31 May 2016) debian
UPSNAME  : APC
...

You’ve completed the UPS / host setup.

InfluxDB Setup

1
2
3
4
5
6
7
8


curl https://repos.influxdata.com/influxdata-archive.key | gpg --dearmor | sudo tee /usr/share/keyrings/influxdb-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/influxdb-archive-keyring.gpg] https://repos.influxdata.com/debian stable main" | sudo tee /etc/apt/sources.list.d/influxdb.list
apt update
apt install influxdb
systemctl unmask influxdb
systemctl enable influxdb
systemctl start influxdb
systemctl status influxdb

I’ll put all the data from your UPS into a separate database.

First, we’ll need to create it and can do so using curl:

1

curl -i -XPOST  "http://localhost:8086/query?q=CREATE+DATABASE+ups"

We can verify successful DB creation again using curl:

1

curl -i -XPOST  "http://localhost:8086/query?q=SHOW+DATABASES"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


 ~  $  influx
Connected to http://localhost:8086 version 1.8.10
InfluxDB shell version: 1.8.10
> show databases
name: databases
name
----
_internal
ups
> use ups
Using database ups
> show measurements
name: measurements
name
----
APC
> select * from APC where time > now() - 1h
name: APC
time                BATTV BCHARGE LOADPCT TIMELEFT host
----                ----- ------- ------- -------- ----
1724517094829361767               5                myups
1724517094891750548 27                             myups
1724517094952570159                       190.7    myups
1724517095013039249       100                      myups
1724517121518211456               5                myups

Note that final entry is ups which is the database we just created. Now we have to move onto scraping the output the UPS generates and write it to the database.

Scraping the UPS output

Note the section near the top tagsArray and compare the items in the array being scraped against the actual output of apcacess as shown above. Pick and choose the items you want and these are what will be written to the database. The name must match exactly else the scraping will fail.

You will also need to modify, near the bottom, your InfluxDB IP. You needed this above for the curl commands.

1
2


vi /opt/scrape.php
chmod +x /opt/scrape.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


#!/usr/bin/php
php

$command = "apcaccess";
$args = "status";
$tagsArray = array(
"LOADPCT",
"BATTV",
"TIMELEFT",
"BCHARGE"
);

//do system call

$call = $command." ".$args;
$output = shell_exec($call);

//parse output for tag and value

foreach ($tagsArray as $tag) {

preg_match("/".$tag."\s*:\s([\d|\.]+)/si", $output, $match);

//send measurement, tag and value to influx

sendDB($match[1], $tag);

}
//end system call

//send to influxdb

function sendDB($val, $tagname) {

$curl = "curl -i -XPOST 'http://localhost:8086/write?db=ups' --data-binary 'APC,host=myups ".$tagname."=".$val."'";
$execsr = exec($curl);

}

?>

You can do a test run with /opt/scrape.php and then verify your InfluxDB logs and look for some successful writes via curl (code 204 = good).

Automating the scraping

We’ll use cron for automating the running of the scraping script. Do not edit the crontab with crontab -e instead you must edit /etc/crontab and specify a user in order for this work.

Add the following line to /etc/crontab, this will run the scraping script every minute.

1

* * * * * root /usr/bin/php /opt/scrape.php >/dev/null 2>&1

Again verify the InfluxDB logs for 204 response codes to check everything went OK.

Grafana Dashboard

The next step is to add a data source in Grafana. Under the configuration menu in Grafana click “Add data source”. Modify the Name, Type = InfluxDB, URL = http://influxdb:8086, Database = ups, User = root, Pass = root . If you modified these values obviously modify to suit.

Then hit save & test.

Next in Grafana click the + icon on the left and select ‘import’. We’ll be importing this awesome dashboardby Marius Gilberg. The ID you need is 7197.

Select your Influx UPS data source as the new data source we just created above and hit import.

Hugo

Tue, 02 Jul 2024 00:00:00 +0000

Hugo File Naming Convention

Hugo gives us two options to name standard page files: as TITLE/index.md or TITLE.md where TITLE is your page name.

The page name should be lowercase and using hyphens (-) instead of spaces.

Both approaches result in the same output, so you can choose your preferred approach to naming and organizing files. A benefit to the folder-based approach is that all your page’s files (such as images) are self-contained within the page’s folder, so it’s more portable if you wish to share the original Markdown page with someone.

The homepage is a special case as Hugo requires the homepage and listing pages to be named _index.md.

The docs navigation is automatically generated based on the content in the docs/ folder and is sorted alphabetically.

The order of pages can be changed by adding the weight parameter in the front matter of your Markdown files.

In the example below, the example.md page will appear before the test.md page as it has a lower weight:

Page example.md:

1
2
3
4


---
title: My Example
weight: 1
---

Page test.md:

1
2
3
4


---
title: My Test
weight: 2
---

Folder Structure

There are 4 main folders for Hugo-based sites:

content/ for your Markdown-formatted content files (homepage, etc.)
_index.md the homepage (Hugo requires that the homepage and archive pages have an underscore prefix)

The content folder contains all the content files for the website.

New items

It is convenient to use archetypes to generate new files easily. By default, the URL of the new paper would be baseURL/papers/new_paper/. But the URL can be customized in the new_paper.md file with the url parameter. For instance, with url: /paperx/, the URL of the new paper is simplified to baseURL/paperx/.

New categories

It is also easy to add new categories to the website, for instance to list software, data, a blog, and so on. For instance to add a list of datasets, create a new data subfolder into the content folder. Then add a content file such as new_dataset.md into the data subfolder. That new category will be available at baseURL/data/. You can for instance link to it with a button from the homepage. To do that, simply add the following snippet into the config.yml file, below profileMode:buttons:

1
2


- name: Datasets
  url: /data/

You can also add a link to the new category in the menu bar. To do that, simply add the following snippet into the config.yml file, below menu:main:

1
2
3


- name: Datasets
  url: /data/
  weight: 4

Static files

The static folder contains all the static files (files not processed or rendered by Hugo) for the website. These include all the PDF files and images to which the website links.

Archetypes

The template comes with archetypes, stored in the archetypes folder. In Hugo, an archetype is a predefined content template that serves as a blueprint for creating new pages. Archetypes help streamline content creation by providing a consistent starting point with predefined metadata and content structure. There is an archetype for paper pages (paper.md) and an archetype for course pages (course.md)

To create a new webpage from an archetype, simply use the hugo new command in the terminal from the website directory. For example, to create a page for a new course, you can run:

hugo new content/courses/my-new-teaching-material.md --kind course

Hugo will generate a new content file called my-new-teaching-material.md and place it the directory content/courses/, where all the courses are stored. Furthermore, Hugo will use the archetype course.md. Then, you can edit the content of the page by modifying the newly created file my-new-teaching-material.md.

Search page

A search page can also be added to the website. To add a search page, move the search.md file from the archetypes folder into the content folder. Then, add the following snippet at the end of the config.yml file so that search works properly:

1
2
3
4
5


outputs:
     home:
         - HTML
         - RSS
         - JSON

Finally, add the following snippet below in the config.yml file to make the search page available from the menu:

1
2
3


- name: Search
  url: /search/
  weight: 6

The search page will be available at baseURL/search/.

The website does not have a footer, but it is possible to add one by setting hideFooter: false in the config.yml file. The footer contains a copyright notice and a “powered by” notice. The footer can be customized by modifying the file layouts/partials/footer.html.

Public folder

The public folder contains the fully generated static website files that are ready to be deployed to GitHub Pages. When you run the hugo command, Hugo processes your content, templates, and other project files and generates a static website. The resulting output is placed in the public folder by default.

The public folder can always be safely deleted. A new version of the public folder will be created when you run the hugo command in the terminal.