# facts

values that winch reads from each host

Facts are values that winch reads from each host before the plan, such as the OS release.

## Reading a fact

Expressions read a fact as facts.os.id, and templates as {{ .facts.os.id }}. Facts are a fixed set. A read of an unknown fact is an error.

```
# winch.yaml
name: demo
hosts:
  web1.example.com: {}
steps:
  - recipe: base
recipes:
  base:
    require:
      - !expr facts.os.id == "debian" and facts.os.version == "13"
    steps:
      - reboot:
          if_required: true
        when: !expr facts.reboot_required

# The plan fails a host that is not Debian 13. A host that needs a
# reboot reboots.
```

## When winch reads them

winch reads the facts once per host per run, before the first step, and again after a reboot. They describe the host before the run.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`os`](#facts.os) | map | - | OS release of the host |
| [`os.id`](#facts.os.id) | string | - | distribution, such as debian or ubuntu |
| [`os.version`](#facts.os.version) | string | - | release number, such as 13 or 24.04 |
| [`os.codename`](#facts.os.codename) | string | - | release code name, such as trixie or noble |
| [`os.arch`](#facts.os.arch) | string | - | CPU architecture: amd64 or arm64 |
| [`reboot_required`](#facts.reboot_required) | boolean | - | pending reboot |

### `facts.os` {#facts.os}

map

OS release of the host. winch reads id, version, and codename from /etc/os-release, or from /usr/lib/os-release when the first does not exist.

### `facts.os.id` {#facts.os.id}

string

Distribution, such as debian or ubuntu.

### `facts.os.version` {#facts.os.version}

string

Release number, such as 13 or 24.04. It is a string: compare it with a string, such as "13".

### `facts.os.codename` {#facts.os.codename}

string

Release code name, such as trixie or noble.

### `facts.os.arch` {#facts.os.arch}

string

CPU architecture: amd64 or arm64.

### `facts.reboot_required` {#facts.reboot_required}

boolean

Pending reboot. It is true when /run/reboot-required exists, or when a kernel in /boot is newer than the running kernel.