References

A reference is a marker in the value of a configuration keyword, replaced during evaluation.

A reference is formatted as {<expression>}.

References can be used to:

• Abstract changing parts of a configuration, so this configuration can be used as a template Example: The object name, object id, the devices that hosts the data

• Factorize information, so changing it is easier and safer Example: A project name used to format the name of different resources (volume group, filesystem path, …)

• Contextualize part of a configuration with information known to the agent Example: The cluster nodes, cluster dns ip addresses, …

Intra-Configuration References

The reference format is {[<section>.]<option>}, where

• <section> is a configuration file section name
• <option> is the option name in the pointed section.

If <section> is omitted, the referencing keyword’s section is implicitly used if the reference can be found locally, or the DEFAULT section is implicitly used.

Intra-Section References

These references can be used inside a configuration section, and their evaluated value depends on the section.

Hard Coded References

Deprecated references:

Capacity

{<rid>.capacity} is how big a resource is, asked of the resource. It is not that resource’s size keyword: the keyword says what the resource was asked to be, and the capacity says what it holds now. The two differ wherever a driver rounds, keeps metadata of its own, or has been grown since.

A resource answers it if it can say how big it is: volume groups, zpools, md arrays, logical volumes, zvols, loop and rados disks, and the filesystems that hold their own size.

It is resolved when the resource exists. A reference to a resource of the same object that is configured but not built yet waits for it to be built, which is what lets a configuration naming one validate before anything is provisioned.

Arithmetic

A reference can be computed on. An expression is written $(...), and what it computes replaces it:

[disk#1]
type = lv
vg = {disk#vg.name}
size = $(50% * {disk#vg.capacity})

The references are resolved first, so what the arithmetic reads is numbers.

Numbers are written the way every other size in a configuration is written, so 10g, 10GB and 1ki are numbers here. Parentheses group, and a leading - negates.

A percent sign means one of two things, told apart by what follows it. A number follows a remainder, and an operator or the end of the expression follows a share, so 9 % 4 is 1 and 50% * 10g is half of ten gibibytes. The spaces around the sign make no difference.

The result is a whole number: a half of an odd number of bytes is one of them or the other, not an error. The drivers round it again to what their storage takes, so a filesystem asked for a third of a volume group lands on the nearest extent below it.

Arithmetic is computed only on keywords that convert to a number — a size, an integer. $(...) is also how a shell substitutes a command, and keywords hold shell commands, so a trigger or the start of an app keeps what it was written with:

[app#1]
type = forking
start = /bin/echo $(date +%s)   # a command, left alone

[disk#0]
type = loop
size = $(2 * 512m)              # a size, computed

References and env Section

The env section can be used to store arbitrary factorized information to make available as references in other parts of the configuration.

Example:

[disk#0]
name = {id}
pvs = {env.devs}

[env]
devs = /dev/vdb

These values can be overridden when creating a new object from this configuration file or template.

om <path> create --config <template> --env devs=/dev/vdc