pkg-pins.d(5)

NAME

pkg-pins.d - local pins: packages this machine resolves to an exact build

SYNOPSIS

/etc/pkg/pins.d/*.toml

DESCRIPTION

A pin says "this name resolves to this build", and this directory is where a machine keeps its own. Two commands write here. pkg-pin(1) writes local.toml, and pkg-rollback(1) writes rollback-<seq>.toml, where <seq> is the rollback's own transaction number. You can write others by hand.

Every .toml file in the directory is read, in name order. The directory itself can be moved with pkg --pins-dir.

The pins sit above every configured repository in the chain. When pkg asks which build of a pinned name to use, the pin answers first. See pkg-chain(7).

FORMAT

# written by pkg rollback --to 47 (transaction #50) [[pin]] name = "openssl" version = "3.5.1" release = 2 sha256 = { lib = "...", bin = "..." } origin = "rollback #50"

name: The package name. A pin covers every subpackage of the name, the same way a repository's pin does.
version, release: The build's label.
sha256: Subpackage to payload digest, for every subpackage that was known when the pin was taken. Two repositories can publish the same version and release with different bytes, and the digests decide which one is meant. A subpackage that has no digest here resolves at the pinned label, from the repository serving the others.
origin: Free text, for people. Optional.

Unknown keys are an error. So is one name pinned twice, in one file or across two, and the error names both places. One name, one pin.

RULES

A pin is not a root

A pin decides which build of an installed name. That's all it does. It doesn't install the name, and it doesn't keep it from being removed, by hand or by pkg-autoremove(1).

A pin outlives the repositories

When every repository drops a name, the pin still resolves to its pinned build as long as some repository serves that build, out of its history if it has to. When none does, the name is held, and a warning says why:

warning: openssl is pinned at 3.5.1-2 by /etc/pkg/pins.d/local.toml, and no configured repo serves that build; holding openssl

The pin isn't dropped. You put it there, so you take it away.

A rollback's pins need their rollback

A rollback-<seq>.toml is ignored, with a warning, when transaction <seq> never committed. That means it's newer than the newest record in the history, or the record with that number isn't the rollback that names this file. The next pkg pin or pkg unpin deletes it.

A record pruned from history doesn't count as never committed. Pruning history doesn't unpin anything.