raft / docs
Reference

Configure locations and defaults

Use host onboarding to create inventory and raft config set to manage defaults. Your controller reads both files from ~/.config/raft/; host note and retention policies are separate and apply across controllers.

Configure a location

~/.config/raft/incus.json maps location names to hosts. This is an illustrative entry; replace the SSH target and fingerprint with your host's values before use:

{
  "lab": {
    "ssh": "ubuntu@192.0.2.10",
    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "note": "Preferred for builds"
  }
}
FieldAccepted value
Location keyStarts with an ASCII letter or digit, then letters, digits, _ or -
sshRequired nonempty SSH target, such as user@host or an alias from ~/.ssh/config
imageFull 64-character lowercase hexadecimal fingerprint for image-based creation; may be empty during provisioning
noteOptional string of operator guidance, not an enforced restriction

ARM64 and AMD64 images have different fingerprints. Image aliases are not accepted. Changing a pin affects future image-based creation, not saved boxes or snapshot copies.

The first inventory location is the built-in creation default; an explicit flag or configured default can override it. raft locations reads the file without contacting hosts and marks the first entry as default, even when config.json selects another location. list, capacity, doctor, gc, prune and the config policy report accept --location; without it they contact all configured hosts.

Use raft note lab "Preferred for builds" or raft note lab --clear to change location guidance. Raft preserves location order and writes mode 0600. For manually edited inventory, run chmod 600 ~/.config/raft/incus.json.

Defaults for new

Optional ~/.config/raft/config.json has one top-level defaults object. For example:

{"defaults": {"location": "lab", "ttl": 3600, "cpu": 2, "memory": "4GiB", "disk": "shared", "disposable": false}}
KeyAccepted valueBuilt-in default
locationConfigured location nameFirst inventory entry
ttl60 to 2,592,000 seconds600
cpuPositive whole number, up to the host CPU count1
memoryPositive whole GiB, such as 16GiB, up to host RAM rounded up to GiB2GiB
diskPositive whole GiB for an own disk, or sharedshared
disposableJSON boolean; true or false in config setfalse

Explicit creation flags win over defaults. Size defaults do not apply to new --from; the snapshot supplies CPU, RAM and disk. A disposable default does apply to snapshot copies. Forks ignore controller defaults entirely. See defaults and policies.

set and unset report changes, write privately and remove the file when no defaults remain. Unknown keys, bad values and malformed JSON fail instead of being ignored. set or unset can repair a recognized key's value; edit malformed JSON or unknown keys directly.

Authenticate over SSH

Verify a host's fingerprint before accepting its key. Configure identities in ~/.ssh/config and confirm ssh -o BatchMode=yes ubuntu@192.0.2.10 'sudo -n true' with your host target.

Raft uses batch SSH without password prompts. Most control, execution and transfer connections use a 10-second connection timeout, not a session-duration limit; recovery and tunnels use SSH defaults without that explicit timeout. An unreachable host does not prove that a remote operation failed or a box is absent.

Control release notices

Set RAFT_NO_UPDATE_CHECK=1 to disable passive release checks. Their cache is $XDG_CACHE_HOME/raft/update.json, or ~/.cache/raft/update.json by default. Notices use stderr and never install an update; global JSON mode suppresses them. See upgrades.

On this page