disk

package
v0.82.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2024 License: Apache-2.0 Imports: 13 Imported by: 4

Documentation

Overview

Package disk contains data types and functions to define and modify disk-related and partition-table-related entities.

The disk package is a collection of interfaces and structs that can be used to represent a disk image with its layout. Various concrete types, such as PartitionTable, Partition and Filesystem types are defined to model a given disk layout. These implement a collection of interfaces that can be used to navigate and operate on the various possible combinations of entities in a generic way. The entity data model is very generic so that it can represent all possible layouts, which can be arbitrarily complex, since technologies like logical volume management, LUKS2 containers and file systems, that can have sub-volumes, allow for complex and nested layouts.

Entity and Container are the two main interfaces that are used to model the tree structure of a disk image layout. The other entity interfaces, such as Sizeable and Mountable, then describe various properties and capabilities of a given entity.

Index

Constants

View Source 
const (
	// Default sector size in bytes
	DefaultSectorSize = 512

	// Default grain size in bytes. The grain controls how sizes of certain
	// entities are rounded. For example, by default, partition sizes are
	// rounded to the next MiB.
	DefaultGrainBytes = uint64(1048576) // 1 MiB

	// UUIDs
	BIOSBootPartitionGUID = "21686148-6449-6E6F-744E-656564454649"
	BIOSBootPartitionUUID = "FAC7F1FB-3E8D-4137-A512-961DE09A5549"

	FilesystemDataGUID = "0FC63DAF-8483-4772-8E79-3D69D8477DE4"
	FilesystemDataUUID = "CB07C243-BC44-4717-853E-28852021225B"

	EFISystemPartitionGUID = "C12A7328-F81F-11D2-BA4B-00A0C93EC93B"
	EFISystemPartitionUUID = "68B2905B-DF3E-4FB3-80FA-49D1E773AA33"
	EFIFilesystemUUID      = "7B77-95E7"

	LVMPartitionGUID = "E6D6D379-F507-44C2-A23C-238F2A3DF928"
	PRePartitionGUID = "9E1A2D38-C612-4316-AA26-8B49521E5A8B"

	RootPartitionUUID = "6264D520-3FB9-423F-8AB8-7A0A8E3D3562"

	// Extended Boot Loader Partition
	XBootLDRPartitionGUID = "BC13C2FF-59E6-4262-A352-B275FD6F7172"
)
View Source 
const DefaultBtrfsCompression = "zstd:1"
View Source 
const LVMDefaultExtentSize = 4 * common.MebiByte

Default physical extent size in bytes: logical volumes created inside the VG will be aligned to this.

Variables

This section is empty.

Functions

func NewVolIDFromRand 

func NewVolIDFromRand(r *rand.Rand) string

NewVolIDFromRand creates a random 32 bit hex string to use as a volume ID for FAT filesystems.

Types

type Argon2id 

type Argon2id struct {
	// Number of iterations to perform.
	Iterations uint

	// Amount of memory to use (in KiB).
	Memory uint

	// Degree of parallelism (i.e. number of threads).
	Parallelism uint
}

Argon2id defines parameters for the key derivation function for LUKS.

type Btrfs 

type Btrfs struct {
	UUID       string
	Label      string
	Mountpoint string
	Subvolumes []BtrfsSubvolume
}

func (*Btrfs) AlignUp 

func (b *Btrfs) AlignUp(size uint64) uint64

func (*Btrfs) Clone 

func (b *Btrfs) Clone() Entity

func (*Btrfs) CreateMountpoint 

func (b *Btrfs) CreateMountpoint(mountpoint string, size uint64) (Entity, error)

func (*Btrfs) EntityName added in v0.70.0 

func (b *Btrfs) EntityName() string

func (*Btrfs) GenUUID 

func (b *Btrfs) GenUUID(rng *rand.Rand)

func (*Btrfs) GetChild 

func (b *Btrfs) GetChild(n uint) Entity

func (*Btrfs) GetItemCount 

func (b *Btrfs) GetItemCount() uint

func (*Btrfs) MetadataSize added in v0.73.0 

func (b *Btrfs) MetadataSize() uint64

type BtrfsSubvolume 

type BtrfsSubvolume struct {
	Name       string
	Size       uint64
	Mountpoint string
	GroupID    uint64
	Compress   string
	ReadOnly   bool

	// UUID of the parent volume
	UUID string
}

func (*BtrfsSubvolume) Clone 

func (bs *BtrfsSubvolume) Clone() Entity

func (*BtrfsSubvolume) EnsureSize 

func (bs *BtrfsSubvolume) EnsureSize(s uint64) bool

func (*BtrfsSubvolume) GetFSSpec 

func (bs *BtrfsSubvolume) GetFSSpec() FSSpec

func (*BtrfsSubvolume) GetFSTabOptions 

func (bs *BtrfsSubvolume) GetFSTabOptions() (FSTabOptions, error)

func (*BtrfsSubvolume) GetFSType 

func (bs *BtrfsSubvolume) GetFSType() string

func (*BtrfsSubvolume) GetMountpoint 

func (bs *BtrfsSubvolume) GetMountpoint() string

func (*BtrfsSubvolume) GetSize 

func (bs *BtrfsSubvolume) GetSize() uint64

type ClevisBind 

type ClevisBind struct {
	Pin    string
	Policy string

	// If enabled, the passphrase will be removed from the LUKS device at the
	// end of the build (using the org.osbuild.luks2.remove-key stage).
	RemovePassphrase bool
}

ClevisBind defines parameters for binding a LUKS device with a given policy.

type Container 

type Container interface {
	Entity

	// GetItemCount returns the number of actual child entities.
	GetItemCount() uint

	// GetChild returns the child entity at the given index.
	GetChild(n uint) Entity
}

Container is the interface for entities that can contain other entities. Together with the base Entity interface this allows to model a generic entity tree of theoretically arbitrary depth and width.

type Entity 

type Entity interface {
	// Clone returns a deep copy of the entity.
	Clone() Entity
}

Entity is the base interface for all disk-related entities.

type EntityCallback 

type EntityCallback func(e Entity, path []Entity) error

type FSSpec 

type FSSpec struct {
	UUID  string
	Label string
}

FSSpec for a filesystem (UUID and Label); the first field of fstab(5)

type FSTabOptions 

type FSTabOptions struct {
	// The fourth field of fstab(5); fs_mntops
	MntOps string
	// The fifth field of fstab(5); fs_freq
	Freq uint64
	// The sixth field of fstab(5); fs_passno
	PassNo uint64
}

func (FSTabOptions) ReadOnly added in v0.70.0 

func (o FSTabOptions) ReadOnly() bool

ReadOnly returns true if the filesystem is mounted read-only.

type Filesystem 

type Filesystem struct {
	Type string
	// ID of the filesystem, vfat doesn't use traditional UUIDs, therefore this
	// is just a string.
	UUID       string
	Label      string
	Mountpoint string
	// The fourth field of fstab(5); fs_mntops
	FSTabOptions string
	// The fifth field of fstab(5); fs_freq
	FSTabFreq uint64
	// The sixth field of fstab(5); fs_passno
	FSTabPassNo uint64
}

Filesystem related functions

func (*Filesystem) Clone 

func (fs *Filesystem) Clone() Entity

Clone the filesystem structure

func (*Filesystem) EntityName added in v0.70.0 

func (fs *Filesystem) EntityName() string

func (*Filesystem) GenUUID 

func (fs *Filesystem) GenUUID(rng *rand.Rand)

func (*Filesystem) GetFSSpec 

func (fs *Filesystem) GetFSSpec() FSSpec

func (*Filesystem) GetFSTabOptions 

func (fs *Filesystem) GetFSTabOptions() (FSTabOptions, error)

func (*Filesystem) GetFSType 

func (fs *Filesystem) GetFSType() string

func (*Filesystem) GetMountpoint 

func (fs *Filesystem) GetMountpoint() string

type LUKSContainer 

type LUKSContainer struct {
	Passphrase string
	UUID       string
	Cipher     string
	Label      string
	Subsystem  string
	SectorSize uint64

	// The password-based key derivation function's parameters.
	PBKDF Argon2id

	// Parameters for binding the LUKS device.
	Clevis *ClevisBind

	Payload Entity
}

LUKSContainer represents a LUKS encrypted volume.

func (*LUKSContainer) Clone 

func (lc *LUKSContainer) Clone() Entity

func (*LUKSContainer) EntityName added in v0.70.0 

func (lc *LUKSContainer) EntityName() string

func (*LUKSContainer) GenUUID 

func (lc *LUKSContainer) GenUUID(rng *rand.Rand)

func (*LUKSContainer) GetChild 

func (lc *LUKSContainer) GetChild(n uint) Entity

func (*LUKSContainer) GetItemCount 

func (lc *LUKSContainer) GetItemCount() uint

func (*LUKSContainer) MetadataSize 

func (lc *LUKSContainer) MetadataSize() uint64

type LVMLogicalVolume 

type LVMLogicalVolume struct {
	Name    string
	Size    uint64
	Payload Entity
}

func (*LVMLogicalVolume) Clone 

func (lv *LVMLogicalVolume) Clone() Entity

func (*LVMLogicalVolume) EnsureSize 

func (lv *LVMLogicalVolume) EnsureSize(s uint64) bool

func (*LVMLogicalVolume) GetChild 

func (lv *LVMLogicalVolume) GetChild(n uint) Entity

func (*LVMLogicalVolume) GetItemCount 

func (lv *LVMLogicalVolume) GetItemCount() uint

func (*LVMLogicalVolume) GetSize 

func (lv *LVMLogicalVolume) GetSize() uint64

type LVMVolumeGroup 

type LVMVolumeGroup struct {
	Name        string
	Description string

	LogicalVolumes []LVMLogicalVolume
}

func (*LVMVolumeGroup) AlignUp 

func (vg *LVMVolumeGroup) AlignUp(size uint64) uint64

func (*LVMVolumeGroup) Clone 

func (vg *LVMVolumeGroup) Clone() Entity

func (*LVMVolumeGroup) CreateLogicalVolume 

func (vg *LVMVolumeGroup) CreateLogicalVolume(lvName string, size uint64, payload Entity) (Entity, error)

func (*LVMVolumeGroup) CreateMountpoint 

func (vg *LVMVolumeGroup) CreateMountpoint(mountpoint string, size uint64) (Entity, error)

func (*LVMVolumeGroup) EntityName added in v0.70.0 

func (vg *LVMVolumeGroup) EntityName() string

func (*LVMVolumeGroup) GetChild 

func (vg *LVMVolumeGroup) GetChild(n uint) Entity

func (*LVMVolumeGroup) GetItemCount 

func (vg *LVMVolumeGroup) GetItemCount() uint

func (*LVMVolumeGroup) MetadataSize 

func (vg *LVMVolumeGroup) MetadataSize() uint64

type Mountable 

type Mountable interface {

	// GetMountPoint returns the path of the mount point.
	GetMountpoint() string

	// GetFSType returns the file system type, e.g. 'xfs'.
	GetFSType() string

	// GetFSSpec returns the file system spec information.
	GetFSSpec() FSSpec

	// GetFSTabOptions returns options for mounting the entity.
	GetFSTabOptions() (FSTabOptions, error)
}

A Mountable entity is an entity that can be mounted.

type MountableCallback 

type MountableCallback func(mnt Mountable, path []Entity) error

type MountpointCreator 

type MountpointCreator interface {
	CreateMountpoint(mountpoint string, size uint64) (Entity, error)

	// AlignUp will align the given bytes according to the
	// requirements of the container type.
	AlignUp(size uint64) uint64
}

A MountpointCreator is a container that is able to create new volumes.

CreateMountpoint creates a new mountpoint with the given size and returns the entity that represents the new mountpoint.

type Partition 

type Partition struct {
	Start    uint64 // Start of the partition in bytes
	Size     uint64 // Size of the partition in bytes
	Type     string // Partition type, e.g. 0x83 for MBR or a UUID for gpt
	Bootable bool   // `Legacy BIOS bootable` (GPT) or `active` (DOS) flag

	// ID of the partition, dos doesn't use traditional UUIDs, therefore this
	// is just a string.
	UUID string

	// If nil, the partition is raw; It doesn't contain a payload.
	Payload PayloadEntity
}

func (*Partition) Clone 

func (p *Partition) Clone() Entity

func (*Partition) EnsureSize 

func (p *Partition) EnsureSize(s uint64) bool

Ensure the partition has at least the given size. Will do nothing if the partition is already larger. Returns if the size changed.

func (*Partition) GetChild 

func (p *Partition) GetChild(n uint) Entity

func (*Partition) GetItemCount 

func (pt *Partition) GetItemCount() uint

func (*Partition) GetSize 

func (p *Partition) GetSize() uint64

func (*Partition) IsBIOSBoot 

func (p *Partition) IsBIOSBoot() bool

func (*Partition) IsPReP 

func (p *Partition) IsPReP() bool

func (*Partition) MarshalJSON added in v0.70.0 

func (p *Partition) MarshalJSON() ([]byte, error)

func (*Partition) UnmarshalJSON added in v0.70.0 

func (p *Partition) UnmarshalJSON(data []byte) error

type PartitionTable 

type PartitionTable struct {
	Size       uint64 // Size of the disk (in bytes).
	UUID       string // Unique identifier of the partition table (GPT only).
	Type       string // Partition table type, e.g. dos, gpt.
	Partitions []Partition

	SectorSize   uint64 // Sector size in bytes
	ExtraPadding uint64 // Extra space at the end of the partition table (sectors)
	StartOffset  uint64 // Starting offset of the first partition in the table (Mb)
}

func NewPartitionTable 

func NewPartitionTable(basePT *PartitionTable, mountpoints []blueprint.FilesystemCustomization, imageSize uint64, mode PartitioningMode, requiredSizes map[string]uint64, rng *rand.Rand) (*PartitionTable, error)

NewPartitionTable takes an existing base partition table and some parameters and returns a new version of the base table modified to satisfy the parameters.

Mountpoints: New filesystems and minimum partition sizes are defined in mountpoints. By default, if new mountpoints are created, a partition table is automatically converted to LVM (see Partitioning modes below).

Image size: The minimum size of the partition table, which in turn will be the size of the disk image. The final size of the image will either be the value of the imageSize argument or the sum of all partitions and their associated metadata, whichever is larger.

Partitioning modes: The mode controls how the partition table is modified.

- Raw will not convert any partition to LVM or Btrfs.

- LVM will convert the partition that contains the root mountpoint '/' to an LVM Volume Group and create a root Logical Volume. Any extra mountpoints, except /boot, will be added to the Volume Group as new Logical Volumes.

- Btrfs will convert the partition that contains the root mountpoint '/' to a Btrfs volume and create a root subvolume. Any extra mountpoints, except /boot, will be added to the Btrfs volume as new Btrfs subvolumes.

- AutoLVM is the default mode and will convert a raw partition table to an LVM-based one if and only if new mountpoints are added.

Directory sizes: The requiredSizes argument defines a map of minimum sizes for specific directories. These indirectly control the minimum sizes of partitions. A directory with a required size will set the minimum size of the partition with the mountpoint that contains the directory. Additional directory requirements are additive, meaning the minimum size for a mountpoint's partition is the sum of all the required directory sizes it will contain. By default, if no requiredSizes are provided, the new partition table will require at least 1 GiB for '/' and 2 GiB for '/usr'. In most cases, this translates to a requirement of 3 GiB for the root partition, Logical Volume, or Btrfs subvolume.

General principles:

Desired sizes for partitions, partition tables, volumes, directories, etc, are always treated as minimum sizes. This means that very often the full disk image size is larger than the size of the sum of the partitions due to metadata. The function considers that the size of volumes have higher priority than the size of the disk.

The partition or volume container that contains '/' is always last in the partition table layout.

In the case of raw partitioning (no LVM and no Btrfs), the partition containing the root filesystem is grown to fill any left over space on the partition table. Logical Volumes are not grown to fill the space in the Volume Group since they are trivial to grow on a live system.

func (*PartitionTable) AlignUp 

func (pt *PartitionTable) AlignUp(size uint64) uint64

AlignUp will round up the given size value to the default grain if not already aligned.

func (*PartitionTable) BytesToSectors 

func (pt *PartitionTable) BytesToSectors(size uint64) uint64

Convert the given bytes to the number of sectors.

func (*PartitionTable) Clone 

func (pt *PartitionTable) Clone() Entity

func (*PartitionTable) ContainsMountpoint 

func (pt *PartitionTable) ContainsMountpoint(mountpoint string) bool

Returns if the partition table contains a filesystem with the given mount point.

func (*PartitionTable) CreateMountpoint 

func (pt *PartitionTable) CreateMountpoint(mountpoint string, size uint64) (Entity, error)

func (*PartitionTable) EnsureDirectorySizes 

func (pt *PartitionTable) EnsureDirectorySizes(dirSizeMap map[string]uint64)

EnsureDirectorySizes takes a mapping of directory paths to sizes (in bytes) and resizes the appropriate partitions such that they are at least the size of the sum of their subdirectories plus their own sizes. The function will panic if any of the directory paths are invalid.

func (*PartitionTable) EnsureSize 

func (pt *PartitionTable) EnsureSize(s uint64) bool

func (*PartitionTable) FindMountable 

func (pt *PartitionTable) FindMountable(mountpoint string) Mountable

FindMountable returns the Mountable entity with the given mountpoint in the PartitionTable. Returns nil if no Entity has the target as a Mountpoint.

func (*PartitionTable) ForEachEntity 

func (pt *PartitionTable) ForEachEntity(cb EntityCallback) error

ForEachEntity runs the provided callback function on each entity in the PartitionTable.

func (*PartitionTable) ForEachMountable 

func (pt *PartitionTable) ForEachMountable(cb MountableCallback) error

ForEachMountable runs the provided callback function on each Mountable in the PartitionTable.

func (*PartitionTable) GenUUID 

func (pt *PartitionTable) GenUUID(rng *rand.Rand)

GenUUID generates and sets UUIDs for all Partitions in the PartitionTable if the layout is GPT.

func (*PartitionTable) GenerateUUIDs 

func (pt *PartitionTable) GenerateUUIDs(rng *rand.Rand)

Generate all needed UUIDs for all the partiton and filesystems

Will not overwrite existing UUIDs and only generate UUIDs for partitions if the layout is GPT.

func (*PartitionTable) GetBuildPackages 

func (pt *PartitionTable) GetBuildPackages() []string

GetBuildPackages returns an array of packages needed to support the features used in the PartitionTable.

func (*PartitionTable) GetChild 

func (pt *PartitionTable) GetChild(n uint) Entity

func (*PartitionTable) GetItemCount 

func (pt *PartitionTable) GetItemCount() uint

func (*PartitionTable) GetMountpointSize added in v0.39.0 

func (pt *PartitionTable) GetMountpointSize(mountpoint string) (uint64, error)

GetMountpointSize takes a mountpoint and returns the size of the entity this mountpoint belongs to.

func (*PartitionTable) GetSize 

func (pt *PartitionTable) GetSize() uint64

func (*PartitionTable) HeaderSize 

func (pt *PartitionTable) HeaderSize() uint64

func (*PartitionTable) SectorsToBytes 

func (pt *PartitionTable) SectorsToBytes(size uint64) uint64

Convert the given number of sectors to bytes.

type PartitioningMode added in v0.12.0 

type PartitioningMode string
const (
	// AutoLVMPartitioningMode creates a LVM layout if the filesystem
	// contains a mountpoint that's not defined in the base partition table
	// of the specified image type. In the other case, a raw layout is used.
	AutoLVMPartitioningMode PartitioningMode = "auto-lvm"

	// LVMPartitioningMode always creates an LVM layout.
	LVMPartitioningMode PartitioningMode = "lvm"

	// RawPartitioningMode always creates a raw layout.
	RawPartitioningMode PartitioningMode = "raw"

	// BtrfsPartitioningMode creates a btrfs layout.
	BtrfsPartitioningMode PartitioningMode = "btrfs"

	// DefaultPartitioningMode is AutoLVMPartitioningMode and is the empty state
	DefaultPartitioningMode PartitioningMode = ""
)

type PayloadEntity added in v0.70.0 

type PayloadEntity interface {
	Entity

	// EntityName is the type name of the Entity, used for marshaling
	EntityName() string
}

PayloadEntity is an entity that can be used as a Payload for a Container.

type Sizeable 

type Sizeable interface {
	// EnsureSize will resize the entity to the given size in case
	// it is currently smaller. Returns if the size was changed.
	EnsureSize(size uint64) bool

	// GetSize returns the size of the entity in bytes.
	GetSize() uint64
}

Sizeable is implemented by entities that carry size information.

type UniqueEntity 

type UniqueEntity interface {
	Entity
	GenUUID(rng *rand.Rand)
}

A UniqueEntity is an entity that can be uniquely identified via a UUID.

GenUUID generates a UUID for the entity if it does not yet have one.

type VolumeContainer 

type VolumeContainer interface {

	// MetadataSize returns the size of the container's metadata (in
	// bytes), i.e. the storage space that needs to be reserved for
	// the container itself, in contrast to the data it contains.
	MetadataSize() uint64
	// contains filtered or unexported methods
}

VolumeContainer is a specific container that contains volume entities

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.