Documentation ¶
Index ¶
- Constants
- Variables
- func ClearTryRecoverySystem(dev Device, systemLabel string) error
- func ComposeCandidateCommandLine(model *asserts.Model) (string, error)
- func ComposeCandidateRecoveryCommandLine(model *asserts.Model, system string) (string, error)
- func ComposeCommandLine(model *asserts.Model) (string, error)
- func ComposeRecoveryCommandLine(model *asserts.Model, system string) (string, error)
- func CopyBootAssetsCacheToRoot(dstRoot string) error
- func DebugDumpBootVars(w io.Writer, dir string, uc20 bool) error
- func DebugSetBootVars(dir string, recoveryBootloader bool, varEqVal []string) error
- func EnsureNextBootToRunMode(systemLabel string) error
- func EnsureNextBootToRunModeWithTryRecoverySystemOutcome(outcome TryRecoverySystemOutcome) error
- func FindPartitionUUIDForBootedKernelDisk() (string, error)
- func GetCurrentBoot(t snap.Type, dev Device) (snap.PlaceInfo, error)
- func InitramfsIsTryingRecoverySystem(currentSystemLabel string) (bool, error)
- func InitramfsReboot() error
- func InitramfsRunModeSelectSnapsToMount(typs []snap.Type, modeenv *Modeenv) (map[snap.Type]snap.PlaceInfo, error)
- func IsInconsistentRecoverySystemState(err error) bool
- func MakeBootableImage(model *asserts.Model, rootdir string, bootWith *BootableSet, ...) error
- func MakeRunnableSystem(model *asserts.Model, bootWith *BootableSet, ...) error
- func MarkBootSuccessful(dev Device) error
- func MockInitramfsReboot(f func() error) (restore func())
- func ModeAndRecoverySystemFromKernelCommandLine() (mode, sysLabel string, err error)
- func SetRecoveryBootSystemAndMode(dev Device, systemLabel, mode string) error
- func SetTryRecoverySystem(dev Device, systemLabel string) (err error)
- func UpdateManagedBootConfigs(dev Device) (updated bool, err error)
- type BootKernel
- type BootParticipant
- type BootableSet
- type Device
- type FDESetupHookParams
- type InUseFunc
- type Modeenv
- type TrustedAssetsInstallObserver
- func (o *TrustedAssetsInstallObserver) ChosenEncryptionKeys(key, saveKey secboot.EncryptionKey)
- func (o *TrustedAssetsInstallObserver) Observe(op gadget.ContentOperation, affectedStruct *gadget.LaidOutStructure, ...) (gadget.ContentChangeAction, error)
- func (o *TrustedAssetsInstallObserver) ObserveExistingTrustedRecoveryAssets(recoveryRootDir string) error
- type TrustedAssetsUpdateObserver
- type TryRecoverySystemOutcome
Constants ¶
const ( // DefaultStatus is the value of a status boot variable when nothing is // being tried DefaultStatus = "" // TryStatus is the value of a status boot variable when something is about // to be tried TryStatus = "try" // TryingStatus is the value of a status boot variable after we have // attempted a boot with a try snap - this status is only set in the early // boot sequence (bootloader, initramfs, etc.) TryingStatus = "trying" )
const ( // ModeRun indicates the regular operating system mode of the device. ModeRun = "run" // ModeInstall is a mode in which a new system is installed on the // device. ModeInstall = "install" // ModeRecover is a mode in which the device boots into the recovery // system. ModeRecover = "recover" )
Variables ¶
var ( // InitramfsRunMntDir is the directory where ubuntu partitions are mounted // during the initramfs. InitramfsRunMntDir string // InitramfsDataDir is the location of system-data role partition // (typically a partition labeled "ubuntu-data") during the initramfs. InitramfsDataDir string // InitramfsHostUbuntuDataDir is the location of the host ubuntu-data // during the initramfs, typically used in recover mode. InitramfsHostUbuntuDataDir string // InitramfsHostWritableDir is the location of the host writable // partition during the initramfs, typically used in recover mode. InitramfsHostWritableDir string // InitramfsUbuntuBootDir is the location of ubuntu-boot during the // initramfs. InitramfsUbuntuBootDir string // InitramfsUbuntuSeedDir is the location of ubuntu-seed during the // initramfs. InitramfsUbuntuSeedDir string // InitramfsUbuntuSaveDir is the location of ubuntu-save during the // initramfs. InitramfsUbuntuSaveDir string // InitramfsWritableDir is the location of the writable partition during the // initramfs. Note that this may refer to a temporary filesystem or a // physical partition depending on what system mode the system is in. InitramfsWritableDir string // InstallHostWritableDir is the location of the writable partition of the // installed host during install mode. This should always be on a physical // partition. InstallHostWritableDir string // InstallHostFDEDataDir is the location of the FDE data during install mode. InstallHostFDEDataDir string // InstallHostFDESaveDir is the directory of the FDE data on the // ubuntu-save partition during install mode. For other modes, // use dirs.SnapSaveFDEDirUnder(). InstallHostFDESaveDir string // InitramfsSeedEncryptionKeyDir is the location of the encrypted partition // keys during the initramfs on ubuntu-seed. InitramfsSeedEncryptionKeyDir string // InitramfsBootEncryptionKeyDir is the location of the encrypted partition // keys during the initramfs on ubuntu-boot. InitramfsBootEncryptionKeyDir string )
var ( HasFDESetupHook = func() (bool, error) { return false, nil } RunFDESetupHook = func(op string, params *FDESetupHookParams) ([]byte, error) { return nil, fmt.Errorf("internal error: RunFDESetupHook not set yet") } )
Hook functions setup by devicestate to support device-specific full disk encryption implementations. The state must be locked when these functions are called.
var ( // ErrBootNameAndRevisionNotReady is returned when the boot revision is not // established yet. ErrBootNameAndRevisionNotReady = errors.New("boot revision not yet established") )
var ErrObserverNotApplicable = errors.New("observer not applicable")
ErrObserverNotApplicable indicates that observer is not applicable for use with the model.
var ErrUnsupportedSystemMode = errors.New("system mode is unsupported")
Functions ¶
func ClearTryRecoverySystem ¶
ClearTryRecoverySystem removes a given candidate recovery system from the modeenv state file, reseals and clears related bootloader variables. An empty system label can be passed when the boot variables state is inconsistent.
func ComposeCandidateCommandLine ¶
ComposeCandidateCommandLine composes the kernel command line used when booting the system in run mode with the current built-in edition of managed boot assets.
func ComposeCandidateRecoveryCommandLine ¶
ComposeCandidateRecoveryCommandLine composes the kernel command line used when booting the given system in recover mode with the current built-in edition of managed boot assets.
func ComposeCommandLine ¶
ComposeCommandLine composes the kernel command line used when booting the system in run mode.
func ComposeRecoveryCommandLine ¶
ComposeRecoveryCommandLine composes the kernel command line used when booting a given system in recover mode.
func CopyBootAssetsCacheToRoot ¶
CopyBootAssetsCacheToRoot copies the boot assets cache to a corresponding location under a new root directory.
func DebugDumpBootVars ¶
DebugDumpBootVars writes a dump of the snapd bootvars to the given writer
func DebugSetBootVars ¶
DebugSetBootVars is a debug helper that takes a list of <var>=<value> entries and sets them for the configured bootloader.
func EnsureNextBootToRunMode ¶
EnsureNextBootToRunMode will mark the bootenv of the recovery bootloader such that recover mode is now ready to switch back to run mode upon any reboot.
func EnsureNextBootToRunModeWithTryRecoverySystemOutcome ¶
func EnsureNextBootToRunModeWithTryRecoverySystemOutcome(outcome TryRecoverySystemOutcome) error
EnsureNextBootToRunModeWithTryRecoverySystemOutcome, typically called while in initramfs, updates the boot environment to indicate an outcome of trying out a recovery system and sets the system up to boot into run mode. It is up to the caller to ensure the status is updated for the right recovery system, typically by calling InitramfsIsTryingRecoverySystem beforehand.
func FindPartitionUUIDForBootedKernelDisk ¶
FindPartitionUUIDForBootedKernelDisk returns the partition uuid for the partition that the booted kernel is located on.
func GetCurrentBoot ¶
GetCurrentBoot returns the currently set name and revision for boot for the given type of snap, which can be snap.TypeBase (or snap.TypeOS), or snap.TypeKernel. Returns ErrBootNameAndRevisionNotReady if the values are temporarily not established.
func InitramfsIsTryingRecoverySystem ¶
InitramfsIsTryingRecoverySystem, typically called while in initramfs of recovery mode system, checks whether the boot variables indicate that the given recovery system is only being tried. When the state of boot variables is inconsistent, eg. status indicates that a recovery system is to be tried, but the label is unset, a specific error which can be tested with IsInconsystemRecoverySystemState() is returned.
func InitramfsReboot ¶
func InitramfsReboot() error
InitramfsReboot requests the system to reboot. Can be called while in initramfs.
func InitramfsRunModeSelectSnapsToMount ¶
func InitramfsRunModeSelectSnapsToMount( typs []snap.Type, modeenv *Modeenv, ) (map[snap.Type]snap.PlaceInfo, error)
InitramfsRunModeSelectSnapsToMount returns a map of the snap paths to mount for the specified snap types.
func MakeBootableImage ¶
func MakeBootableImage(model *asserts.Model, rootdir string, bootWith *BootableSet, sealer *TrustedAssetsInstallObserver) error
MakeBootableImage sets up the given bootable set and target filesystem such that the image can be booted.
rootdir points to an image filesystem (UC 16/18) or an image recovery filesystem (UC20 at prepare-image time). On UC20, bootWith.Recovery must be true, as this function makes the recovery system bootable. It does not make a run system bootable, for that functionality see MakeRunnableSystem, which is meant to be used at runtime from UC20 install mode.
func MakeRunnableSystem ¶
func MakeRunnableSystem(model *asserts.Model, bootWith *BootableSet, sealer *TrustedAssetsInstallObserver) error
MakeRunnableSystem is like MakeBootableImage in that it sets up a system to be able to boot, but is unique in that it is intended to be called from UC20 install mode and makes the run system bootable (hence it is called "runnable"). Note that this function does not update the recovery bootloader env to actually transition to run mode here, that is left to the caller via something like boot.EnsureNextBootToRunMode(). This is to enable separately setting up a run system and actually transitioning to it, with hooks, etc. running in between.
func MarkBootSuccessful ¶
MarkBootSuccessful marks the current boot as successful. This means that snappy will consider this combination of kernel/os a valid target for rollback.
The states that a boot goes through for UC16/18 are the following:
- By default snap_mode is "" in which case the bootloader loads two squashfs'es denoted by variables snap_core and snap_kernel.
- On a refresh of core/kernel snapd will set snap_mode=try and will also set snap_try_{core,kernel} to the core/kernel that will be tried next.
- On reboot the bootloader will inspect the snap_mode and if the mode is set to "try" it will set "snap_mode=trying" and then try to boot the snap_try_{core,kernel}".
- On a successful boot snapd resets snap_mode to "" and copies snap_try_{core,kernel} to snap_{core,kernel}. The snap_try_* values are cleared afterwards.
- On a failing boot the bootloader will see snap_mode=trying which means snapd did not start successfully. In this case the bootloader will set snap_mode="" and the system will boot with the known good values from snap_{core,kernel}
func MockInitramfsReboot ¶
func MockInitramfsReboot(f func() error) (restore func())
func ModeAndRecoverySystemFromKernelCommandLine ¶
ModeAndRecoverySystemFromKernelCommandLine returns the current system mode and the recovery system label as passed in the kernel command line by the bootloader.
func SetRecoveryBootSystemAndMode ¶
SetRecoveryBootSystemAndMode configures the recovery bootloader to boot into the given recovery system in a particular mode. Returns ErrUnsupportedSystemMode when booting into a recovery system is not supported by the device.
func SetTryRecoverySystem ¶
SetTryRecoverySystem sets up the boot environment for trying out a recovery system with given label and adds the new system to the list of current recovery systems in the modeenv. Once done, the caller should request switching to the given recovery system.
func UpdateManagedBootConfigs ¶
UpdateManagedBootConfigs updates managed boot config assets if those are present for the ubuntu-boot bootloader. Returns true when an update was carried out.
Types ¶
type BootKernel ¶
type BootKernel interface { // RemoveKernelAssets removes the unpacked kernel/initrd for the given // kernel snap. RemoveKernelAssets() error // ExtractKernelAssets extracts kernel/initrd/dtb data from the given // kernel snap, if required, to a versioned bootloader directory so // that the bootloader can use it. ExtractKernelAssets(snap.Container) error // Is this a trivial implementation of the interface? IsTrivial() bool }
A BootKernel handles the bootloader setup of a kernel.
type BootParticipant ¶
type BootParticipant interface { // SetNextBoot will schedule the snap to be used in the next boot. For // base snaps it is up to the caller to select the right bootable base // (from the model assertion). It is a noop for not relevant snaps. // Otherwise it returns whether a reboot is required. SetNextBoot() (rebootRequired bool, err error) // Is this a trivial implementation of the interface? IsTrivial() bool }
A BootParticipant handles the boot process details for a snap involved in it.
func Participant ¶
Participant figures out what the BootParticipant is for the given arguments, and returns it. If the snap does _not_ participate in the boot process, the returned object will be a NOP, so it's safe to call anything on it always.
Currently, on classic, nothing is a boot participant (returned will always be NOP).
type BootableSet ¶
type BootableSet struct { Base *snap.Info BasePath string Kernel *snap.Info KernelPath string RecoverySystemLabel string RecoverySystemDir string UnpackedGadgetDir string // Recover is set when making the recovery partition bootable. Recovery bool }
BootableSet represents the boot snaps of a system to be made bootable.
type Device ¶
type Device interface { RunMode() bool Classic() bool Kernel() string Base() string HasModeenv() bool Model() *asserts.Model }
Device carries information about the device model and mode that is relevant to boot. Note snapstate.DeviceContext implements this, and that's the expected use case.
type FDESetupHookParams ¶
type FDESetupHookParams struct { Key secboot.EncryptionKey KeyName string Models []*asserts.Model }
FDESetupHookParams contains the inputs for the fde-setup hook
type Modeenv ¶
type Modeenv struct { Mode string `key:"mode"` RecoverySystem string `key:"recovery_system"` // CurrentRecoverySystems is a list of labels corresponding to recovery // systems that have been tested or are in the process of being tried, // thus only the run key is resealed for these systems. CurrentRecoverySystems []string `key:"current_recovery_systems"` // GoodRecoverySystems is a list of labels corresponding to recovery // systems that were tested and are prepared to use for recovering. // The fallback keys are resealed for these systems. GoodRecoverySystems []string `key:"good_recovery_systems"` Base string `key:"base"` TryBase string `key:"try_base"` BaseStatus string `key:"base_status"` CurrentKernels []string `key:"current_kernels"` Model string `key:"model"` BrandID string `key:"model,secondary"` Grade string `key:"grade"` // CurrentTrustedBootAssets is a map of a run bootloader's asset names to // a list of hashes of the asset contents. Typically the first entry in // the list is a hash of an asset the system currently boots with (or is // expected to have booted with). The second entry, if present, is the // hash of an entry added when an update of the asset was being applied // and will become the sole entry after a successful boot. CurrentTrustedBootAssets bootAssetsMap `key:"current_trusted_boot_assets"` // CurrentTrustedRecoveryBootAssetsMap is a map of a recovery bootloader's // asset names to a list of hashes of the asset contents. Used similarly // to CurrentTrustedBootAssets. CurrentTrustedRecoveryBootAssets bootAssetsMap `key:"current_trusted_recovery_boot_assets"` // CurrentKernelCommandLines is a list of the expected kernel command // lines when booting into run mode. It will typically only be one // element for normal operations, but may contain two elements during // update scenarios. CurrentKernelCommandLines bootCommandLines `key:"current_kernel_command_lines"` // contains filtered or unexported fields }
Modeenv is a file on UC20 that provides additional information about the current mode (run,recover,install)
func ReadModeenv ¶
ReadModeenv attempts to read the modeenv file at <rootdir>/var/iib/snapd/modeenv.
type TrustedAssetsInstallObserver ¶
type TrustedAssetsInstallObserver struct {
// contains filtered or unexported fields
}
TrustedAssetsInstallObserver tracks the installation of trusted or managed boot assets.
func TrustedAssetsInstallObserverForModel ¶
func TrustedAssetsInstallObserverForModel(model *asserts.Model, gadgetDir string, useEncryption bool) (*TrustedAssetsInstallObserver, error)
TrustedAssetsInstallObserverForModel returns a new trusted assets observer for use during installation of the run mode system to track trusted and control managed assets, provided the device model indicates this might be needed. Otherwise, nil and ErrObserverNotApplicable is returned.
func (*TrustedAssetsInstallObserver) ChosenEncryptionKeys ¶
func (o *TrustedAssetsInstallObserver) ChosenEncryptionKeys(key, saveKey secboot.EncryptionKey)
func (*TrustedAssetsInstallObserver) Observe ¶
func (o *TrustedAssetsInstallObserver) Observe(op gadget.ContentOperation, affectedStruct *gadget.LaidOutStructure, root, relativeTarget string, data *gadget.ContentChange) (gadget.ContentChangeAction, error)
Observe observes the operation related to the content of a given gadget structure. In particular, the TrustedAssetsInstallObserver tracks writing of trusted or managed boot assets, such as the bootloader binary which is measured as part of the secure boot or the bootloader configuration.
Implements gadget.ContentObserver.
func (*TrustedAssetsInstallObserver) ObserveExistingTrustedRecoveryAssets ¶
func (o *TrustedAssetsInstallObserver) ObserveExistingTrustedRecoveryAssets(recoveryRootDir string) error
ObserveExistingTrustedRecoveryAssets observes existing trusted assets of a recovery bootloader located inside a given root directory.
type TrustedAssetsUpdateObserver ¶
type TrustedAssetsUpdateObserver struct {
// contains filtered or unexported fields
}
TrustedAssetsUpdateObserver tracks the updates of trusted boot assets and attempts to reseal when needed or preserves managed boot assets.
func TrustedAssetsUpdateObserverForModel ¶
func TrustedAssetsUpdateObserverForModel(model *asserts.Model, gadgetDir string) (*TrustedAssetsUpdateObserver, error)
TrustedAssetsUpdateObserverForModel returns a new trusted assets observer for tracking changes to the trusted boot assets and preserving managed assets, provided the device model indicates this might be needed. Otherwise, nil and ErrObserverNotApplicable is returned.
func (*TrustedAssetsUpdateObserver) BeforeWrite ¶
func (o *TrustedAssetsUpdateObserver) BeforeWrite() error
BeforeWrite is called when the update process has been staged for execution.
func (*TrustedAssetsUpdateObserver) Canceled ¶
func (o *TrustedAssetsUpdateObserver) Canceled() error
Canceled is called when the update has been canceled, or if changes were written and the update has been reverted.
func (*TrustedAssetsUpdateObserver) Observe ¶
func (o *TrustedAssetsUpdateObserver) Observe(op gadget.ContentOperation, affectedStruct *gadget.LaidOutStructure, root, relativeTarget string, data *gadget.ContentChange) (gadget.ContentChangeAction, error)
Observe observes the operation related to the update or rollback of the content of a given gadget structure. In particular, the TrustedAssetsUpdateObserver tracks updates of trusted boot assets such as bootloader binaries, or preserves managed assets such as boot configuration.
Implements gadget.ContentUpdateObserver.
type TryRecoverySystemOutcome ¶
type TryRecoverySystemOutcome int
const ( TryRecoverySystemOutcomeFailure TryRecoverySystemOutcome = iota TryRecoverySystemOutcomeSuccess // TryRecoverySystemOutcomeInconsistent indicates that the booted try // recovery system state was incorrect and corresponding boot variables // need to be cleared TryRecoverySystemOutcomeInconsistent // TryRecoverySystemOutcomeNoneTried indicates a state in which no // recovery system has been tried TryRecoverySystemOutcomeNoneTried )
func InspectTryRecoverySystemOutcome ¶
func InspectTryRecoverySystemOutcome(dev Device) (outcome TryRecoverySystemOutcome, label string, err error)
InspectTryRecoverySystemOutcome obtains a tried recovery system status. When no recovery system has been tried, the outcome will be TryRecoverySystemOutcomeNoneTried. The caller is responsible for clearing the bootenv once the status bas been properly acted on.