pkg-rollback(1)

NAME

pkg-rollback - return the installed set to a recorded transaction

SYNOPSIS

pkg rollback [--to N] [--transient] [--dry-run] [--force]

DESCRIPTION

The upgrade went in, and now something's broken. You want yesterday back.

Without --to, pkg rollback undoes the newest transaction in pkg-history(1). With --to N, it returns to the state right after transaction N. --to 0, on a machine whose history starts at #1, goes back to the state before that.

What does it actually do?

It's one transaction, and it:

installs every subpackage the target names, at exactly its payload digest, whichever direction that moves it;
removes every installed subpackage the target doesn't name;
sets the selection roots to what they were in the target.

It finds the old builds the same way pkg upgrade --to does: in the current sets of the configured repositories first, then in their superseded history. If any build the target needs is no longer served, the rollback is refused before anything changes, and every missing build is named.

The rollback gets a number of its own, like any other transaction. Undoing it is just another rollback.

PINS

Why does it write a pins file?

Because otherwise the very next pkg upgrade moves everything right back to where you just left. So a rollback writes /etc/pkg/pins.d/rollback-<seq>.toml, where <seq> is the rollback's own transaction number. That file pins every name whose target build differs from what the repositories currently name. The next upgrade reports those names as held by a pin. When you're ready to move forward again, release them with pkg unpin (see pkg-pin(1)).

Rolling back to a point before an earlier rollback removes that rollback's pins. Any other pin that conflicts with the target refuses the rollback.

If you only want to try whether an older build helps, pass --transient and nothing gets pinned at all.

WHAT IS NOT ROLLED BACK

Files are rolled back. System state is not. Triggers have already run, and data a newer version migrated stays migrated. Edited files under /etc follow the usual rules: your edits stay, and a changed default lands as .pkgnew. pkg says so at the end of every rollback, because it's easy to forget.

If you need an atomic rollback, that's what slice and image deployments are for.

REFUSALS

A rollback refuses, and changes nothing, when:

Nothing is recorded: There's no transaction in the history to go back from.
The store changed outside pkg: The installed set isn't what the newest transaction left. Then no recorded state describes where the machine is, and pkg won't guess.
The target is beyond the history: A number equal to or newer than the newest, or older than what retention kept; see [history] in pkg.toml(5).
A build no repository serves: Each one is named, before anything changes.
A pin is in the way: A local pin, other than an earlier rollback's that this one undoes, holds a name at a different build than the target.

OPTIONS

--to N: Return to the state right after transaction N, as pkg-history(1) lists it.
--transient: Pin nothing. The output tells you how many packages the next pkg upgrade will move forward again. For trying whether an older build helps.
--dry-run: Print the plan, change nothing.
--force: Push past removal blockers: a running process that maps an outgoing file, a kernel module that's loaded. Never past a pin.

All global options apply; see pkg(1).

CONFIRMATION

A rollback can remove packages, so it prompts at the default confirm level of destructive.

JSON

The plan document of pkg-upgrade(1), plus rollback_to, pin (the names it pins) and unpin_files (earlier rollbacks' pins files it removes).

EXAMPLES

Undo the last thing that happened

Look first, then do it:

pkg history -n 5 pkg rollback --dry-run pkg rollback

Go back further

pkg rollback --to 41

Done debugging, let upgrades through again

pkg unpin --all

EXIT STATUS

0 on success. 1 on any refusal above, or any failure applying the plan.