Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Facts and Templates

Facter and Core Facts

Learn how Facter collects facts about each node, how to read the structured $facts hash in manifests, and how to branch on operating system, memory and network data.

Puppet manifests describe the state you want, but the right state often depends on the machine. A web server package is called apache2 on Debian and httpd on Red Hat. A node with 64 GB of RAM deserves a bigger cache than one with 2 GB. Facter is the tool that tells Puppet what each machine looks like: before every catalog is compiled, the agent runs Facter and sends the result to the server as facts.

Facts are plain data. They are collected on the node, they are read-only for your code, and inside a manifest they are available as the top-scope $facts hash. This lesson shows the fact structure, the facts you will use daily, and how to write code that adapts to them. The product itself cannot run on this site, so the commands are read-only examples and the runnable blocks are small stand-ins that imitate fact lookups.

Looking at facts from the command line

On any machine with the agent installed you can ask Facter directly:

Terminal
facter                      # every fact, as nested key-value output
facter os                   # one structured fact
facter os.family            # a nested value with dot notation
facter --json networking    # machine readable output
facter -p                   # also load facts shipped in Puppet modules

Running facter on its own prints a long document in a JSON-like layout. The exact content depends on the machine, so this lesson never shows invented output: run it on a test machine and read it once from top to bottom. It is the best way to learn what is available.

Structured facts and the $facts hash

Modern Facter returns structured facts: values can be strings, numbers, booleans, arrays or nested hashes. The os fact, for instance, is a hash that holds the family, name and release data:

PUPPET
$family  = $facts['os']['family']                 # e.g. "Debian" or "RedHat"
$major   = $facts['os']['release']['major']       # e.g. "12" or "9"
$cpus    = $facts['processors']['count']
$memory  = $facts['memory']['system']['total']    # human readable string
$address = $facts['networking']['ip']
$name    = $facts['networking']['fqdn']

Always prefer $facts['...'] over the old style of bare top-scope variables such as $::osfamily or $operatingsystem. Those legacy facts still exist when the agent is configured to send them, but they are being removed and they do not show structure. Using the hash also makes it obvious in code review that a value comes from the node and not from a variable you defined.

Facts are untrusted input. The node reports them, so a compromised or misconfigured node can claim anything. For decisions about who may receive secrets, use trusted facts ($trusted), which are taken from the node's certificate, not from Facter.

The facts worth knowing

Fact What it holds
os.family, os.name, os.release.major The operating system, used for package and path differences
kernel, kernelrelease Kernel name and version
networking.fqdn, networking.hostname, networking.ip Names and primary address
memory.system.total_bytes Physical RAM as a number you can compute with
processors.count, processors.models CPU details
disks, mountpoints Block devices and mounted file systems
virtual, is_virtual Hypervisor name, or physical
timezone, uptime, path Misc system data
ssh, partitions, dmi Host keys, partition table, hardware info

Use the _bytes variants for arithmetic. Strings such as "7.65 GiB" are meant for people and are awkward in code.

Branching on facts

The typical use is a case or selector over a fact, often at the top of a class that hides the platform differences:

PUPPET
class webserver {
  $package = $facts['os']['family'] ? {
    'Debian' => 'apache2',
    'RedHat' => 'httpd',
    default  => fail("Unsupported OS family: ${facts['os']['family']}"),
  }

  package { $package:
    ensure => installed,
  }

  service { $package:
    ensure  => running,
    enable  => true,
    require => Package[$package],
  }
}

The selector (? { ... }) returns a value. The default branch calls fail() on purpose: it is better to stop compiling than to guess. Later lessons move such lookups into Hiera data, see Profiles with Hiera and Parameters.

Facts can also drive sizing. A common sizing rule keeps a database buffer at a quarter of memory:

PUPPET
$buffer_mb = floor($facts['memory']['system']['total_bytes'] / 1048576 / 4)

A stand-in for fact lookup

Real Facter runs on the node. The block below is a JavaScript stand-in: it models a facts hash for two imaginary nodes and a helper that resolves dotted paths like facter os.family does. It teaches the lookup logic, not Facter's collection code.

JS Stand-in: dotted fact lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the last line: a missing fact returns undefined here. In Puppet a missing key in $facts gives undef, which is falsy and can silently choose the wrong branch. Guard important lookups with fail() or pick().

JS Stand-in: platform selector with a safe default

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Facts at compile time

The order of events matters for design. Facts are gathered on the agent before the catalog request, uploaded, and then used by the server's compiler. A fact that changes while a run is in progress (for instance because a package just installed new hardware drivers) is not seen until the next run. Never write code that expects a resource earlier in the same catalog to change a fact.

sequenceDiagram
  participant A as Agent
  participant F as Facter
  participant S as Server
  A->>F: collect facts
  F-->>A: structured facts
  A->>S: request catalog with facts
  S-->>A: compiled catalog
  A->>A: apply catalog
  A->>S: send report

Facts travel up with the catalog request; the catalog travels down.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Facter run?

    Facter runs on the node. The agent uploads the facts when it asks the server for a catalog.
  2. 2. Which is the recommended way to read the OS family in a manifest?

    The structured $facts hash is the supported interface; bare legacy variables are being retired.
  3. 3. Why use memory.system.total_bytes instead of memory.system.total in calculations?

    Strings like "7.65 GiB" are for display. The numeric _bytes fact can be divided and compared.
  4. 4. A selector over os.family has no default branch and a node reports an unexpected family. What is a good default?

    Failing compilation loudly beats configuring the wrong package on an unsupported platform.

Summary

  • Facter collects facts on the node; the agent uploads them with the catalog request.
  • Use the structured $facts['os']['family'] style, and numeric _bytes facts for maths.
  • Facts are untrusted input: use $trusted data for security decisions.
  • Branch with selectors or case, and always handle the unknown case explicitly.
  • Run facter on a test machine to see what you can use.

Next: Custom and External Facts