GRAPHS.CFG(5)

✨ graphs.cfg — the manual, but make it make sense ✨

okay bestie, so this is graphs.cfg, and it lives in section 5 of the File Formats Manual. it's a config file. it's not scary. i promise. 🫶

---

🌸 NAME 🌸

graphs.cfg — the configuration file for the showgraph CGI. that's it. that's the whole job. 💅

---

🦋 SYNOPSIS 🦋

$XYMONHOME/etc/graphs.cfg

that's the path. she lives there. periodt.

---

💖 DESCRIPTION 💖

so showgraph.cgi(1) reads this file — $XYMONHOME/etc/graphs.cfg — to build graphs out of the RRD files that Xymon has been collecting. that's the vibe. graphs go brrr. 📈✨

---

🎀 FILE FORMAT 🎀

every graph type definition starts with a [SERVICE] marker, and that name is literally the name that gets passed as the service parameter to showgraph.cgi(1). it's giving "name tag at a party" energy. 🏷️

and here's the tea: if the service name you pass to showgraph.cgi isn't found, it'll try to match that service name to a graph through the TEST2RRD environment variable instead. so calling showgraph.cgi with service=cpu or service=la will end up producing the same graph. lowkey iconic that they're the same thing. 😌

every graph definition needs a TITLE and a YAXIS setting. TITLE is the text shown as the title of the graph, YAXIS is the YAXIS heading. (the X-axis is always time-based, no notes, it's just time. ⏰)

if your graph uses a fixed set of RRD files, you just write those straight into the RRDtool definitions. and don't stress about hostnames — Xymon keeps all the RRD files for a host in a separate directory per host, so you don't need to worry about the hostname being part of the RRD filename. bestie said no hostname anxiety. 🧘‍♀️

for graphs that pull in multiple RRD files as input, you specify a filename pattern in the FNPATTERN statement, and optionally a pattern of files to exclude from the graph with EXFNPATTERN (go peek at [tcp] for an example, it's right there). when FNPATTERN is in play, you can use these little magic tokens in the RRDtool definitions:

• @RRDFN@ — picks up each filename
• @RRDIDX@ — an index (starting at 0) for each file in the set
• @RRDPARAM@ — contains the first word extracted from the pattern of files (see [memory] for how this one gets used)
• @COLOR@ — picks a new color for each graph automatically 🌈

and the remainder of the lines in each definition? they get passed directly to the RRDtool rrd_graph() routine. no middleman. straight through. 💫

---

🍓 the "la" (cpu) graph, aka the simple one 🍓

here's an example of how the la (cpu) graph is defined. simple girl, single RRD-file, la.rrd:

[la]
        TITLE CPU Load
        YAXIS Load
        DEF:avg=la.rrd:la:AVERAGE
        CDEF:la=avg,100,/
        AREA:la#00CC00:CPU Load Average
        GPRINT:la:LAST:  %5.1lf (cur)
        GPRINT:la:MAX:  %5.1lf (max)
        GPRINT:la:MIN:  %5.1lf (min)
        GPRINT:la:AVERAGE:  %5.1lf (avg)\n

---

🧚 and here's the multi-file one, she's fancy 🧚

this graph uses multiple RRD-files, figured out automatically at run-time via the FNPATTERN setting. notice how it uses @RRDIDX@ to define a unique RRD parameter per input-file, and @COLOR@ plus @RRDPARAM@ to pick unique colors and matching text for the graph legend. she's doing the most and i respect it. 👑

[disk]
        FNPATTERN disk(.*).rrd
        TITLE Disk Utilization
        YAXIS % Full
        DEF:p@RRDIDX@=@RRDFN@:pct:AVERAGE
        LINE2:p@RRDIDX@#@COLOR@:@RRDPARAM@
        -u 100
        -l 0
        GPRINT:p@RRDIDX@:LAST:  %5.1lf (cur)
        GPRINT:p@RRDIDX@:MAX:  %5.1lf (max)
        GPRINT:p@RRDIDX@:MIN:  %5.1lf (min)
        GPRINT:p@RRDIDX@:AVERAGE:  %5.1lf (avg)\n

---

👑 ADVANCED GRAPH TITLES 👑

normally the title of a graph is a static text defined right there in the graphs.cfg file. chill. predictable. love that for us.

but — there may be situations where you want different titles for the same type of graph, like if you're incorporating RRD files from MRTG into Xymon. in that case you can set up the TITLE definition so it runs a custom script to determine the graph title. like this:

TITLE exec:/usr/local/bin/graphitle

(that's graphitle spelled exactly like that in the original, bestie, i'm not touching it. 🫡)

so the /usr/local/bin/graphtitle command is then called with the hostname, the graphtype, the period string, and all of the RRD files used as parameters. the script must generate one line of output, and that output is what's used as the title of the graph. and heads up: each of the RRD pathname parameters will be enclosed in double quotes. "like this" 💬

---

🌈 ENVIRONMENT 🌈

• TEST2RRD — maps service names to graph definitions. that's the whole thing. one env var, doing her little job. 💜

---

💀 NOTES 💀

most of the RRD graph definitions shipped with Xymon have been ported from the definitions in the larrd-grapher.cgi CGI from LARRD 0.43c. respect the ancestors. 🙏

---

🔥 SEE ALSO 🔥

• xymonserver.cfg(5)
• rrdtool(1)
• rrdgraph(1)

---

okay that's genuinely everything, no cap. go make some graphs, they're gonna eat. 💅✨

---

signing off from the Xymon manual, Version 4.3.30: 4 Sep 2019. mwah. 🎀