Categorygithub.com/containers/storage
modulepackage
1.57.1
Repository: https://github.com/containers/storage.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
51
Dependents
668
Files
9.6k SLOC

# README

storage is a Go library which aims to provide methods for storing filesystem layers, container images, and containers. A containers-storage CLI wrapper is also included for manual and scripting use.

To build the CLI wrapper, use 'make binary'.

Operations which use VMs expect to launch them using 'vagrant', defaulting to using its 'libvirt' provider. The boxes used are also available for the 'virtualbox' provider, and can be selected by setting $VAGRANT_PROVIDER to 'virtualbox' before kicking off the build.

The library manages three types of items: layers, images, and containers.

A layer is a copy-on-write filesystem which is notionally stored as a set of changes relative to its parent layer, if it has one. A given layer can only have one parent, but any layer can be the parent of multiple layers. Layers which are parents of other layers should be treated as read-only.

An image is a reference to a particular layer (its top layer), along with other information which the library can manage for the convenience of its caller. This information typically includes configuration templates for running a binary contained within the image's layers, and may include cryptographic signatures. Multiple images can reference the same layer, as the differences between two images may not be in their layer contents.

A container is a read-write layer which is a child of an image's top layer, along with information which the library can manage for the convenience of its caller. This information typically includes configuration information for running the specific container. Multiple containers can be derived from a single image.

Layers, images, and containers are represented primarily by 32 character hexadecimal IDs, but items of each kind can also have one or more arbitrary names attached to them, which the library will automatically resolve to IDs when they are passed in to API calls which expect IDs.

The library can store what it calls metadata for each of these types of items. This is expected to be a small piece of data, since it is cached in memory and stored along with the library's own bookkeeping information.

Additionally, the library can store one or more of what it calls big data for images and containers. This is a named chunk of larger data, which is only in memory when it is being read from or being written to its own disk file.

Contributing Information about contributing to this project.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

CheckEverything returns a CheckOptions with every check enabled.
CheckMost returns a CheckOptions with mostly just "quick" checks enabled.
DefaultConfigFile returns the path to the storage config file used.
DefaultStoreOptions returns the default storage options for containers.
GetDefaultMountOptions returns the default mountoptions defined in container/storage.
Deprecated: Use lockfile.GetLockFile.
GetMountOptions returns the mountoptions for the specified driver and graphDriverOptions.
Deprecated: Use lockfile.GetROLockFile.
GetStore attempts to find an already-created Store object matching the specified location and graph driver, and if it can't, it creates and initializes a new Store object, and the underlying storage that it controls.
ParseIDMapping takes idmappings and subuid and subgid maps and returns a storage mapping.
ReloadConfigurationFile parses the specified configuration file and overrides the configuration in storeOptions.
RepairEverything returns a RepairOptions with every optional remediation enabled.
SetDefaultConfigFilePath sets the default configuration to the specified path, and loads the file.

# Constants

AutoUserNsMaxSize is the maximum size for automatically created user namespaces.
AutoUserNsMinSize is the minimum size for automatically created user namespaces.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
ImageDigestBigDataKey is provided for compatibility with older versions of the image library.
ImageDigestManifestBigDataNamePrefix is a prefix of big data item names which we consider to be manifests, used for computing a "digest" value for the image as a whole, by which we can locate the image later.
RootAutoUserNsUser is the default user used for root containers when automatically creating a user namespace.

# Variables

ErrContainerDataIncorrectSize describes a container which has a big data item which looks like its size has changed, likely because it's been modified somehow.
ErrContainerDataMissing describes a container which is missing a big data item.
ErrContainerImageMissing describes a container which claims to be based on an image that we don't know about.
ErrContainerUnknown indicates that there was no container with the specified name or ID.
ErrDigestUnknown indicates that we were unable to compute the digest of a specified item.
ErrDuplicateID indicates that an ID which is to be assigned to a new item is already being used.
ErrDuplicateImageNames indicates that the read-only store uses the same name for multiple images.
ErrDuplicateLayerNames indicates that the read-only store uses the same name for multiple layers.
ErrDuplicateName indicates that a name which is to be assigned to a new item is already being used.
ErrImageDataIncorrectSize describes an image which has a big data item which looks like its size has changed, likely because it's been modified somehow.
ErrImageDataMissing describes an image which is missing a big data item.
ErrImageLayerMissing describes an image which claims to have a layer that we don't know about.
ErrImageUnknown indicates that there was no image with the specified name or ID.
ErrImageUsedByContainer is returned when the caller attempts to delete an image that is a container's image.
ErrIncompleteOptions is returned when the caller attempts to initialize a Store without providing required information.
ErrInvalidBigDataName indicates that the name for a big data item is not acceptable; it may be empty.
ErrInvalidMappings is returned when the specified mappings are invalid.
ErrLayerContentModified describes a layer which contains contents which should not be there, or for which ownership/permissions/dates have been changed.
ErrLayerDataMissing describes a layer which is missing a big data item.
ErrLayerHasChildren is returned when the caller attempts to delete a layer that has children.
ErrLayerIncorrectContentDigest describes a layer for which the contents of one or more files which were added in the layer appear to have changed.
ErrLayerIncorrectContentSize describes a layer for which regenerating the diff that was used to populate the layer produced a diff of a different size.
ErrLayerMissing describes a layer which is the missing parent of a layer.
ErrLayerNotMounted is returned when the requested information can only be computed for a mounted layer, and the layer is not mounted.
ErrLayerUnaccounted describes a layer that is present in the lower-level storage driver, but which is not known to or managed by the higher-level driver-agnostic logic.
ErrLayerUnknown indicates that there was no layer with the specified name or ID.
ErrLayerUnreferenced describes a layer which is not used by any image or container.
ErrLayerUsedByContainer is returned when the caller attempts to delete a layer that is a container's layer.
ErrLayerUsedByImage is returned when the caller attempts to delete a layer that is an image's top layer.
ErrLoadError indicates that there was an initialization error.
ErrNotAContainer is returned when the caller attempts to delete a container that isn't a container.
ErrNotALayer is returned when the caller attempts to delete a layer that isn't a layer.
ErrNotAnID is returned when the caller attempts to read or write metadata from an item that doesn't exist.
ErrNotAnImage is returned when the caller attempts to delete an image that isn't an image.
ErrNotSupported is returned when the requested functionality is not supported.
ErrParentIsContainer is returned when a caller attempts to create a layer as a child of a container's layer.
ErrParentUnknown indicates that we didn't record the ID of the parent of the specified layer.
ErrSizeUnknown is returned when the caller asks for the size of a big data item, but the Store couldn't determine the answer.
ErrStoreIsReadOnly is returned when the caller makes a call to a read-only store that would require modifying its contents.

# Structs

ApplyStagedLayerOptions contains options to pass to ApplyStagedLayer.
CheckOptions is the set of options for Check(), specifying which tests to perform.
CheckReport is a list of detected problems.
A Container is a reference to a read-write layer with metadata.
No description provided by the author
ContainerOptions is used for passing options to a Store's CreateContainer() method.
DedupArgs is used to pass arguments to the Dedup command.
DiffOptions override the default behavior of Diff() methods.
An Image is a reference to a layer and an associated metadata string.
No description provided by the author
ImageOptions is used for passing options to a Store's CreateImage() method.
A Layer is a record of a copy-on-write layer that's stored by the lower level graph driver.
No description provided by the author
LayerOptions is used for passing options to a Store's CreateLayer() and PutLayer() methods.
MultiListOptions contains options to pass to MultiList.
MultiListResult contains slices of Images, Layers or Containers listed by MultiList method.
RepairOptions is the set of options for Repair().

# Interfaces

AdditionalLayer represents a layer that is contained in the additional layer store This API is experimental and can be changed without bumping the major version number.
ContainerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ContainerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
FileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
FlaggableStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ImageStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
LayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
LayerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
MetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROFileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROImageStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROLayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROLayerStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
ROMetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
RWFileBasedStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
RWImageBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
RWLayerBigDataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
RWMetadataStore is a deprecated interface with no documented way to use it from callers outside of c/storage.
Store wraps up the various types of file-based stores that we use into a singleton object that initializes and manages them all together.

# Type aliases

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Deprecated: Use lockfile.*LockFile.
No description provided by the author