RRDGRAPH_DATA(1)

💅 NAME 💅

ok so this is rrdgraph_data from the rrdtool fam — it's literally the whole "preparing data for graphing in rrdtool graph" situation. bestie, this is where your data gets ready before it gets pretty. ✨

---

🎀 SYNOPSIS 🎀

DEF:<vname>=<rrdfile>:<ds-name>:<CF>[:step=<step>][:start=<time>][:end=<time>][:reduce=<CF>][:daemon=<address>]

VDEF:vname=RPN expression

CDEF:vname=RPN expression

---

🦋 DESCRIPTION 🦋

okay so these three little instructions are the ones that go into your RRD files and pull data values out — and yes, they can also tweak those values on the way out (think converting bytes to bits, that kind of glow-up 💫). and if you're feeling extra, you can also define variables that hold genuinely useful info like maximum, minimum, etcetera. two of these instructions speak a whole language called RPN, and RPN has its own manual page (iykyk).

now, variable names (vname) have to be strings you make up yourself, and they can only contain these characters: "A-Z, a-z, 0-9, _, -" — and the max length is 255 characters. no cap, that's the limit.

🫶 real talk: when you're picking variable names, pls pls PLS don't pick something that's already taken by an RPN operator. the safe bet? use lowercase or mixed-case names for your variables, because operators are always gonna be in UPPERCASE. that's the vibe check that saves you.

---

💖 DEF 💖

DEF:<vname>=<rrdfile>:<ds-name>:<CF>[:step=<step>][:start=<time>][:end=<time>][:reduce=<CF>][:daemon=<address>]

this command fetches data from an RRD file, periodt. the virtual name vname can then be used throughout the rest of your script like it's the main character 👑.

by default, an RRA that contains the correct consolidated data at an appropriate resolution gets chosen for you. the resolution can be overridden with the --step option — and then it can again be overridden by specifying the step size. yes, twice. that's not a typo, that's just how it is 🙈.

the time span of this data is the same as the graph's by default, and you can override that by specifying start and end. remember to escape colons in the time specification! (this is the part where everyone gets got 😭)

if the resolution of the data is higher than the resolution of the graph, the data gets further consolidated. this may result in a graph that spans slightly more time than you requested — lowkey annoying but that's the deal. ideally each point in the graph should correspond with one CDP from an RRA. for instance, if your RRD has an RRA with a resolution of 1800 seconds per CDP, you should create an image with width 400 and time span 400*1800 seconds (use appropriate start and end times, such as "--start end-8days8hours").

if consolidation needs to be done, the CF of the RRA specified in the DEF itself will be used to reduce the data density. you can change this behavior using ":reduce=<CF>" — that optional parameter specifies the CF to use during the data reduction phase. slay, customisation 💅

it's also possible to request single data sources from a specific RRDCacheD (see rrdcached) using the ":daemon=<address>" parameter. the value you give it follows the same syntax as other means of specifying the address of the caching daemon, and it's described in detail in rrdcached.

⚠️ beware though: colons (in IPv6 addresses, and as a port separator, for example) need to be escaped using a backslash. don't skip this, fr fr.

example:

DEF:ds0=router.rrd:ds0:AVERAGE
DEF:ds0weekly=router.rrd:ds0:AVERAGE:step=7200
DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=end-1h
DEF:ds0weekly=router.rrd:ds0:AVERAGE:start=11\:00:end=start+1h
DEF:ds0weekly=router.rrd:ds0:AVERAGE:daemon=collect1.example.com

---

🌸 VDEF 🌸

VDEF:vname=RPN expression

this command returns a value and/or a time, according to the RPN statements you used. the resulting vname will — depending on the functions used — have a value component and a time component. when you use this vname in another RPN expression, you're effectively inserting its value just as if you'd put a number right there in that spot. the variable can also be used in the various graph and print elements. iconic.

example: "VDEF:avg=mydata,AVERAGE"

💀 heads up: currently ONLY aggregation functions work in VDEF RPN expressions. patches to change this are welcome (be the change you want to see in the world 🫶).

---

⭐ CDEF ⭐

CDEF:vname=RPN expression

this command creates a whole new set of data points — in memory only, NOT in the RRD file, don't get it twisted — out of one or more other data series. the RPN instructions are used to evaluate a mathematical function on each data point. the resulting vname can then be used further on in the script, just as if it had been generated by a DEF instruction.

example: "CDEF:mydatabits=mydata,8,*"

---

🌈 About CDEF versus VDEF 🌈

at some point in processing, RRDtool has gathered an array of rates that are ready to display.

CDEF works on such an array. for example, CDEF:new=ds0,8,* would multiply each of the array members by eight (probably transforming bytes into bits). the result is an array containing the new values.

VDEF also works on such an array, but in a different way. for example, VDEF:max=ds0,MAXIMUM would scan each of the array members and store the maximum value.

🧚 When do you use VDEF versus CDEF? 🧚

use CDEF to transform your data prior to graphing. in the above example, we'd use a CDEF to transform bytes to bits before graphing the bits.

you use a VDEF if you want max(1,5,3,2,4) to return five, which would be displayed in the graph's legend (to answer, what was the maximum value during the graph period).

if you want to apply 'complex' operations to the result of a VDEF, you have to use a CDEF again — since VDEFs only look like RPN expressions, they aren't really. plot twist 😭

---

🍓 SEE ALSO 🍓

• rrdgraph gives an overview of how rrdtool graph works.
• rrdgraph_data describes DEF, CDEF and VDEF in detail.
• rrdgraph_rpn describes the RPN language used in the ?DEF statements.
• rrdgraph_graph page describes all of the graph and print functions.

make sure to read rrdgraph_examples for tips&tricks — genuinely worth it, no cap 🫶

---

👑 AUTHOR 👑

program by Tobias Oetiker <tobi@oetiker.ch>

this manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl> with corrections and/or additions by several people

---

✨ that's the whole page bestie ✨ this lil masterpiece comes to you from version 1.11.0, dated 2026-10-17, and it's the RRDGRAPH_DATA(1) page — go forth and graph 💖🎀🦋