dwww Home | Manual pages | Find package

containers-storage - Manage layer/image/container storage

containers-storage [subcommand] [--help]

The   containers-storage   command   is   a   front-end  for  the
containers/storage library.  While  it  can  be  used  to  manage
storage  for  filesystem layers, images, and containers directly,
its main  use  cases  are  centered  around  troubleshooting  and
querying  the  state  of  storage which is being managed by other
processes.

Notionally,  a  complete  filesystem  layer  is  composed  of   a
container  filesystem  and  some  bookkeeping information.  Other
layers, children of that layer, default to sharing its  contents,
but  any  changes  made  to  the contents of the children are not
reflected in the parent.  This arrangement is  intended  to  save
disk  space:  by storing the child layer only as a set of changes
relative to its parent, the parent’s contents should not need  to
be duplicated for each of the parent’s children.  Of course, each
child  can  have its own children.  The contents of parent layers
should not be modified.

An image is a reference to a particular layer,  along  with  some
bookkeeping information.  Presumably, the image points to a layer
which  has  been  modified, possibly in multiple steps, from some
general-purpose parent, so that it is  suitable  for  running  an
intended  application.   Multiple  images  can reference a single
layer,  while  differing  only  in  the  additional   bookkeeping
information  that  they  carry.  The contents of images should be
considered read-only.

A container is essentially a layer which is a child  of  a  layer
which is referred to by an image (put another way, a container is
instantiated   from   an  image),  along  with  some  bookkeeping
information.  They do not have children and their layers can  not
be  directly referred to by images.  This ensures that changes to
the contents of a container’s layer do not affect other images or
layers, so they are considered writeable.

All of layers, images, and containers  can  have  metadata  which
containers-storage  manages  attached  to  them.   Generally this
metadata is not expected to be large, as it is cached in memory.

Images and containers can also have arbitrarily-named data  items
attached  to  them.   Generally,  this  data  can  be larger than
metadata, and is not kept in memory unless it is being  retrieved
or written.

It  is  expected  that  signatures which can be used to verify an
image’s contents will be stored as data  items  for  that  image,
along  with  any template configuration data which is recommended
for use in containers which derive from the image.   It  is  also
expected that a container’s run-time configuration will be stored
as data items.

The  containers-storage  command’s  features are broken down into
several subcommands:
 containers-storage  add-names(1)                    Add   layer,
image, or container name or names

containers-storage applydiff(1)                   Apply a diff to
a layer

containers-storage applydiff-using-staging-dir(1) Apply a diff to
a layer staging the new content first.

containers-storage   changes(1)                      Compare  two
layers

containers-storage check(1)                       Check  for  and
possibly remove damaged layers/images/containers

containers-storage   container(1)                     Examine   a
container

containers-storage containers(1)                  List containers

containers-storage create-container(1)             Create  a  new
container from an image

containers-storage  create-image(1)                 Create  a new
image using layers

containers-storage create-layer(1)                 Create  a  new
layer

containers-storage  create-storage-layer(1)         Create  a new
layer in the lower-level storage driver

containers-storage delete(1)                      Delete a  layer
or image or container, with no safety checks

containers-storage    delete-container(1)              Delete   a
container, with safety checks

containers-storage   delete-image(1)                  Delete   an
image, with safety checks

containers-storage delete-layer(1)                Delete a layer,
with safety checks

containers-storage   diff(1)                         Compare  two
layers

containers-storage  diffsize(1)                     Compare   two
layers

containers-storage   exists(1)                       Check  if  a
layer or image or container exists

containers-storage get-container-data(1)          Get  data  that
is attached to a container

containers-storage  get-image-data(1)               Get data that
is attached to an image

containers-storage  image(1)                         Examine   an
image

containers-storage images(1)                      List images

containers-storage layers(1)                      List layers

containers-storage list-container-data(1)         List data items
that are attached to a container

containers-storage list-image-data(1)             List data items
that are attached to an image

containers-storage metadata(1)                    Retrieve layer,
image, or container metadata

containers-storage  mount(1)                        Mount a layer
or container

containers-storage mounted(1)                     Check if a file
system is mounted

containers-storage set-container-data(1)          Set  data  that
is attached to a container

containers-storage  set-image-data(1)               Set data that
is attached to an image

containers-storage  set-metadata(1)                  Set   layer,
image, or container metadata

containers-storage   set-names(1)                     Set  layer,
image, or container name or names

containers-storage shutdown(1)                    Shut down graph
driver

containers-storage status(1)                      Check on  graph
driver status

containers-storage unmount(1)                     Unmount a layer
or container

containers-storage  unshare(1)                      Run a command
in a user namespace

containers-storage     version(1)                          Return
containers-storage version information

containers-storage    wipe(1)                          Wipe   all
layers, images, and containers

--help

Print the list of available sub-commands.  When a sub-command  is
specified, provide information about that command.

--debug, -D

Increases the amount of debugging information which is printed.

--graph, -g=/var/lib/containers/storage

Overrides  the  root  of the storage tree, used for storing layer
contents and information about layers, images, and containers.

--run, -R=/run/containers/storage

Overrides the root of the  runtime  state  tree,  currently  used
mainly  for  noting  the  location where a given layer is mounted
(see containers-storage mount) so that it  can  be  unmounted  by
path name as an alternative to unmounting by ID or name.

--storage-driver, -s

Specifies   which  storage  driver  to  use.   If  not  set,  but
$STORAGE_DRIVER is set in the environment, its value is used.  If
the storage tree has previously been initialized,  neither  needs
to  be provided.  If the tree has not previously been initialized
and neither is set, a hard-coded default is selected.

--storage-opt=[]

Set options which will be passed to the storage driver.   If  not
set,  but  $STORAGE_OPTS  is set in the environment, its value is
treated as a comma-separated  list  and  used  instead.   If  the
storage  tree  has previously been initialized, these need not be
provided.

--unshare, -U

When started by a  non-root  user,  run  inside  of  a  new  user
namespace  configured  using the system’s default ID mappings for
the non-root user.

CONTAINERS_STORAGE_CONF

If  set  will  use  the  configuration  file  path  provided   in
$CONTAINERS_STORAGE_CONF      instead      of     the     default
/etc/containers/storage.conf.

containers-storage layers -t

This is still a work in progress, so some functionality  may  not
yet be implemented, and some will be removed if it is found to be
unnecessary.   That  said,  if  anything isn’t working correctly,
please   report   it   to    the    project’s    issue    tracker
⟨https://github.com/containers/storage/issues⟩.

The  Containers  Storage  project  is committed to inclusivity, a
core  value  of  open  source.   The  master  and   slave   mount
propagation   terminology  is  used  in  this  repository.   This
language is problematic and  divisive,  and  should  be  changed.
However,  these  terms are currently used within the Linux kernel
and must be used as-is at this time.  When the kernel maintainers
rectify  this  usage,  Containers  Storage   will   follow   suit
immediately.

Generated by dwww version 1.16 on Mon Nov 2 10:28:47 CET 2026.