github.com/sshnaidm/storage@v1.12.13/docs/containers-storage.md (about) 1 ## containers-storage 1 "August 2016" 2 3 ## NAME 4 containers-storage - Manage layer/image/container storage 5 6 ## SYNOPSIS 7 **containers-storage** [**subcommand**] [**--help**] 8 9 ## DESCRIPTION 10 The *containers-storage* command is a front-end for the *containers/storage* library. 11 While it can be used to manage storage for filesystem layers, images, and 12 containers directly, its main use cases are centered around troubleshooting and 13 querying the state of storage which is being managed by other processes. 14 15 Notionally, a complete filesystem layer is composed of a container filesystem 16 and some bookkeeping information. Other layers, *children* of that layer, 17 default to sharing its contents, but any changes made to the contents of the 18 children are not reflected in the *parent*. This arrangement is intended to 19 save disk space: by storing the *child* layer only as a set of changes relative 20 to its *parent*, the *parent*'s contents should not need to be duplicated for 21 each of the *parent*'s *children*. Of course, each *child* can have its own 22 *children*. The contents of *parent* layers should not be modified. 23 24 An *image* is a reference to a particular *layer*, along with some bookkeeping 25 information. Presumably, the *image* points to a *layer* which has been 26 modified, possibly in multiple steps, from some general-purpose *parent*, so 27 that it is suitable for running an intended application. Multiple *images* can 28 reference a single *layer*, while differing only in the additional bookkeeping 29 information that they carry. The contents of *images* should be considered 30 read-only. 31 32 A *container* is essentially a *layer* which is a *child* of a *layer* which is 33 referred to by an *image* (put another way, a *container* is instantiated from 34 an *image*), along with some bookkeeping information. They do not have 35 *children* and their *layers* can not be directly referred to by *images*. 36 This ensures that changes to the contents of a *container*'s layer do not 37 affect other *images* or *layers*, so they are considered writeable. 38 39 All of *layers*, *images*, and *containers* can have metadata which 40 *containers-storage* manages attached to them. Generally this metadata is not 41 expected to be large, as it is cached in memory. 42 43 *Images* and *containers* can also have arbitrarily-named data items attached 44 to them. Generally, this data can be larger than metadata, and is not kept in 45 memory unless it is being retrieved or written. 46 47 It is expected that signatures which can be used to verify an *image*'s 48 contents will be stored as data items for that *image*, along with any template 49 configuration data which is recommended for use in *containers* which derive 50 from the *image*. It is also expected that a *container*'s run-time 51 configuration will be stored as data items. 52 53 Files belonging to a *readonly* *layer* will become deduplicated with *OSTree* if the configuration option *storage.ostree_repo* for saving the corresponding OSTree repository is provided. 54 This option won't work if *containers-storage* gets built without support for OSTree. 55 56 ## SUB-COMMANDS 57 The *containers-storage* command's features are broken down into several subcommands: 58 **containers-storage add-names(1)** Add layer, image, or container name or names 59 60 **containers-storage applydiff(1)** Apply a diff to a layer 61 62 **containers-storage changes(1)** Compare two layers 63 64 **containers-storage container(1)** Examine a container 65 66 **containers-storage containers(1)** List containers 67 68 **containers-storage create-container(1)** Create a new container from an image 69 70 **containers-storage create-image(1)** Create a new image using layers 71 72 **containers-storage create-layer(1)** Create a new layer 73 74 **containers-storage delete(1)** Delete a layer or image or container, with no safety checks 75 76 **containers-storage delete-container(1)** Delete a container, with safety checks 77 78 **containers-storage delete-image(1)** Delete an image, with safety checks 79 80 **containers-storage delete-layer(1)** Delete a layer, with safety checks 81 82 **containers-storage diff(1)** Compare two layers 83 84 **containers-storage diffsize(1)** Compare two layers 85 86 **containers-storage exists(1)** Check if a layer or image or container exists 87 88 **containers-storage get-container-data(1)** Get data that is attached to a container 89 90 **containers-storage get-image-data(1)** Get data that is attached to an image 91 92 **containers-storage image(1)** Examine an image 93 94 **containers-storage images(1)** List images 95 96 **containers-storage layers(1)** List layers 97 98 **containers-storage list-container-data(1)** List data items that are attached to a container 99 100 **containers-storage list-image-data(1)** List data items that are attached to an image 101 102 **containers-storage metadata(1)** Retrieve layer, image, or container metadata 103 104 **containers-storage mount(1)** Mount a layer or container 105 106 **containers-storage mounted(1)** Check if a file system is mounted 107 108 **containers-storage set-container-data(1)** Set data that is attached to a container 109 110 **containers-storage set-image-data(1)** Set data that is attached to an image 111 112 **containers-storage set-metadata(1)** Set layer, image, or container metadata 113 114 **containers-storage set-names(1)** Set layer, image, or container name or names 115 116 **containers-storage shutdown(1)** Shut down graph driver 117 118 **containers-storage status(1)** Check on graph driver status 119 120 **containers-storage unmount(1)** Unmount a layer or container 121 122 **containers-storage version(1)** Return containers-storage version information 123 124 **containers-storage wipe(1)** Wipe all layers, images, and containers 125 126 ## OPTIONS 127 **--help** 128 129 Print the list of available sub-commands. When a sub-command is specified, 130 provide information about that command. 131 132 **--debug, -D** 133 134 Increases the amount of debugging information which is printed. 135 136 **--graph, -g=/var/lib/containers/storage** 137 138 Overrides the root of the storage tree, used for storing layer contents and 139 information about layers, images, and containers. 140 141 **--run, -R=/var/run/containers/storage** 142 143 Overrides the root of the runtime state tree, currently used mainly for noting 144 the location where a given layer is mounted (see **containers-storage mount**) so that 145 it can be unmounted by path name as an alternative to unmounting by ID or name. 146 147 **--storage-driver, -s** 148 149 Specifies which storage driver to use. If not set, but *$STORAGE_DRIVER* is 150 set in the environment, its value is used. If the storage tree has previously 151 been initialized, neither needs to be provided. If the tree has not previously 152 been initialized and neither is set, a hard-coded default is selected. 153 154 **--storage-opt=[]** 155 156 Set options which will be passed to the storage driver. If not set, but 157 *$STORAGE_OPTS* is set in the environment, its value is treated as a 158 comma-separated list and used instead. If the storage tree has previously been 159 initialized, these need not be provided. 160 161 ## EXAMPLES 162 **containers-storage layers -t** 163 164 ## BUGS 165 This is still a work in progress, so some functionality may not yet be 166 implemented, and some will be removed if it is found to be unnecessary. That 167 said, if anything isn't working correctly, please report it to [the project's 168 issue tracker] (https://github.com/containers/storage/issues).