Skip to navigation
Resource reference

Resource conventions

Every resource declares one host object, or one command, under a label. Labels can differ from physical names/paths. Rivet rejects conflicting physical ownership, including conflicts between package providers or membership policies.

Approved executable plugins can add resource types and service and package backends. Their declarations follow the same metadata, ownership, capability, and verification rules; each installed definition supplies its schema and static exports.

Managed and unmanaged properties

A default such as ensure = "present" defines desired state. An omitted optional property often means unmanaged: Rivet preserves what exists. The per-resource tables distinguish these cases. Explicit null acts as omission only when that field permits null.

A file’s omitted mode preserves an existing mode but uses 0644 on creation. A service’s omitted activity, enablement, and mask remain unmanaged. User creation uses distribution defaults for omitted fields; omitted existing-user properties remain unmanaged.

ensure is a resource-specific vocabulary, not a generic command:

ResourceAccepted valuesOmitted value
Filefile, directory, symlink, absent; present aliases filefile
Packagepresent, latest, absent, purged; dpkg rejects latestpresent
User / group / group membershippresent, absentpresent
Servicerunning, stopped; state aliases the fieldActivity unmanaged
Timer / SSH keypresent, absentpresent
MountUses state: mounted, unmounted, absentmounted
ExecNo ensure fieldExplicit execution policy required

Explicit null is rejected for non-service ensure policies. Source aliases normalize before evaluation; supplying both service ensure and state fails.

Static exports

Handles and these declared properties can be used in expressions. Optional unmanaged values are unavailable, rather than read from a host. Every type additionally exposes meta.sensitive.

TypeExported properties
Filepath, ensure, content, mode, target, owner, group
Packagename, ensure, version, architecture, held
Username, ensure, uid, primary_group, groups, home, shell, comment, password_hash, password_locked, expires
Groupname, ensure, gid
Group membershipgroup, ensure, members, exclusive
Execcwd
Serviceprovider, name, ensure/state, enabled, masked, on_change
Timername, ensure
SSH keyuser, ensure, explicit authorized_keys
Mountpath, state

For file content, only inline content is available; a source does not expose downloaded bytes through an expression. Account IDs allocated by the host cannot be exported when omitted. Use names when depending on a managed account with an allocated ID.

All types accept common metadata. Required capabilities are checked when compiling and before executing a received bundle.