NAME

       containers-storage - Manage layer/image/container storage

SYNOPSIS

       containers-storage [subcommand] [--help]

DESCRIPTION

       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.

SUB-COMMANDS

       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 changes(1)             Compare two layers

       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 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 version(1)             Return containers-storage version information

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

OPTIONS

       --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=/var/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.

EXAMPLES

       containers-storage layers -t

BUGS

       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⟩.

                                                   August 2016                             containers-storage(1)