1STRATIS(8) STRATIS(8)
2
6 stratis - Configure Stratis local storage pools
7
9 stratis [GLOBAL OPTIONS] pool <command> [args] [COMMAND OPTIONS]
10 stratis [GLOBAL OPTIONS] filesystem|fs <command> [args] [COMMAND OPTIONS]
11 stratis [GLOBAL OPTIONS] blockdev <command> [args] [COMMAND OPTIONS]
12 stratis [GLOBAL OPTIONS] key <command> [args] [COMMAND OPTIONS]
13 stratis [GLOBAL OPTIONS] report <report_name>
14 stratis [GLOBAL OPTIONS] daemon <version>
15
17 stratis is a command-line tool to create, modify, and destroy Stratis
18 pools, and the filesystems allocated from the pool.
19 Stratis creates a pool from one or more block devices (blockdevs), and
21 then enables multiple filesystems to be created from the pool. The user
22 can set keys for use with pool encryption.
23
25 --version
26 Show stratis-cli version.
27 --help, -h
29 Show help on command.
30 --propagate
32 (For debugging.) Allow exceptions raised during execution to
33 propagate.
34 --unhyphenated-uuids
36 (For listing.) Print pool and filesystem UUIDs without hyphens for
37 list commands.
38
40 pool create [--key-desc <key_desc>] [--clevis <(nbde|tang|tpm2)>
41 [--tang-url <tang_url>] [<(--thumbprint <thp> | --trust-url)>]
42 [--no-overprovision] <pool_name> <blockdev> [<blockdev>..]
43 Create a pool from one or more block devices, with the given pool
44 name.
45 pool stop <pool_name>
47 Stop a pool. Tear down the storage stack but leave all metadata
48 intact.
49 pool start <(--uuid <uuid> |--name <name>)> --unlock-method <(keyring |
51 clevis)>
52 Start a pool, speciying the pool by its UUID or by its name. Use
53 the --unlock-method option to specify method of unlocking the pool
54 if it is encrypted.
55 pool list [--stopped] [(--uuid <uuid> |--name <name>)]
57 List pools. If the --stopped option is used, list only stopped
58 pools. Otherwise, list only started pools. If a UUID or name is
59 specified, print more detailed information about the pool
60 corresponding to that UUID or name.
61 pool rename <old_pool_name> <new_pool_name>
63 Rename a pool.
64 pool destroy <pool_name>
66 Destroy a pool and all the filesystems created from it.
67 pool add-data <pool_name> <blockdev> [<blockdev>..]
69 Add one or more blockdevs to an existing pool, to enlarge its
70 storage capacity.
71 pool init-cache <pool_name> <blockdev> [<blockdev>..]
73 Initialize a cache for an existing pool. Add one or more blockdevs
74 to a pool, to be used as cache instead of additional storage.
75 Typically, smaller and faster drives, such as SSDs, are used for
76 this purpose.
77 pool add-cache <pool_name> <blockdev> [<blockdev>..]
79 Add one or more blockdevs to an existing pool with an initialized
80 cache.
81 pool extend-data <pool_name> [--device-uuid <uuid>]
83 Increase the pool’s data capacity with additional storage space
84 offered by its component data devices through, e.g., expansion of a
85 component RAID device. Devices may be specified by their Stratis
86 UUID. If no devices are specified, then stratisd will attempt to
87 make use of all data devices belonging to the pool that appear to
88 have been expanded.
89 pool bind <(nbde|tang)> <pool name> <url> <(--thumbprint <thp> |
91 --trust-url)>
92 Bind the devices in the specified pool to a supplementary
93 encryption mechanism that uses NBDE (Network-Bound Disc
94 Encryption). tang is an alias for nbde.
95 pool bind tpm2 <pool name>
97 Bind the devices in the specified pool to a supplementary
98 encryption mechanism that uses TPM 2.0 (Trusted Platform Module).
99 pool bind keyring <pool name> <keydesc>
101 Bind the devices in the specified pool to a supplementary
102 encryption mechanism using a key in the kernel keyring.
103 pool rebind clevis <pool name>
105 Rebind the devices in the spcified pool using the Clevis
106 configuration with which the devices in the pool were previously
107 bound.
108 pool rebind keyring <pool_name> <keydesc>
110 Rebind the devices in the specified pool using the specified key
111 description.
112 pool unbind <(clevis|keyring)> <pool name>
114 Unbind the devices in the specified pool from the specified
115 encryption mechanism.
116 pool set-fs-limit <pool name> <amount>
118 Set the limit on the number of file systems allowed per-pool. This
119 number may only be increased from its current value.
120 pool overprovision <pool name> <(yes|no)>
122 Set overprovisioning mode. If set to "yes", the pool may allow
123 overprovisioning, i.e, the sum of the logical sizes of the Stratis
124 filesystems supported by the pool may exceed the amount of data
125 space available.
126 pool explain <code>
128 Explain any code that might show up in the Alerts column when
129 listing a pool. Codes may be prefixed with an "I" for "info", a "W"
130 for "warning", or an "E" for "error".
131 pool debug get-object-path <(--uuid <uuid> |--name <name>)>
133 Look up the D-Bus object path for a pool given the UUID or name.
134 filesystem create <pool_name> <fs_name> [<fs_name>..] [--size <size>]
136 Create one or more filesystems from the specified pool. If --size
137 option is specified, make each filesystem the specified size.
138 Otherwise, accept the stratisd default. NOTE: There is a temporary
139 restriction on the number of filesystems that can be specified with
140 this command. Specifying more than one filesystem will result in an
141 error.
142 filesystem snapshot <pool_name> <fs_name> <snapshot_name>
144 Snapshot the filesystem in the specified pool.
145 filesystem list [pool_name]
147 List all filesystems that exist in the specified pool, or all
148 pools, if no pool name is given.
149 filesystem destroy <pool_name> <fs_name> [<fs_name>..]
151 Destroy one or more filesystems that exist in the specified pool.
152 filesystem rename <pool_name> <fs_name> <new_name>
154 Rename a filesystem.
155 filesystem debug get-object-path <(--uuid <uuid> |--name <name>)>
157 Look up the D-Bus object path for a filesystem given the UUID or
158 name.
159 blockdev list [pool_name]
161 List all blockdevs that make up the specified pool, or all pools,
162 if no pool name is given.
163 blockdev debug get-object-path <(--uuid <uuid>)>
165 Look up the D-Bus object path for a blockdev given the UUID.
166 key list
168 List all key-descriptions in the kernel keyring that can be used
169 for encryption.
170 key set <(--keyfile-path <path> | --capture-key)> <key_desc>
172 Set a key in the kernel keyring for use with encryption.
173 key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
175 Reset the key data of an existing key in the kernel keyring.
176 key unset <key_desc>
178 Unset a key in the kernel keyring so it is no longer available for
179 encryption operations.
180 report <report_name>
182 Get a report from the daemon regarding its internal state. The
183 engine_state_report name will be supported in future releases. Any
184 other report name should be considered unstable and may be removed
185 in a future release. The JSON schema of any report must always be
186 considered unstable.
187 daemon version
189 Show the Stratis service’s version.
190 debug refresh
192 For all pools that are not stopped, rebuild their storage stacks
193 from the pool-level metadata stored on each pool’s devices. This is
194 not a standard administrative command; it is intended for
195 trouble-shooting and repair only.
196
198 --key-desc
199 The key description of the key that should be used to encrypt the
200 created pool. The key description must correspond to a key set in
201 the kernel keyring with the key command.
202 --keyfile-path <path> | --capture-key
204 These mutually exclusive options allow a user to specify a key used
205 for encryption in one of two ways. The --keyfile-path option
206 requires an argument, the path to a file containing the key. If the
207 --capture-key option is selected instead, the user must enter the
208 key at the ensuing prompt. The key value is terminated at the first
209 newline character that the user enters, and does not include the
210 newline character. On the other hand, if the file specified as an
211 argument for the --keyfile-path option contains a newline character
212 anywhere, the newline character will be included in the key value.
213 --thumbprint <thp> | --trust-url
215 These mutually exclusive options allow a user to specify that a
216 tang server’s URL should be trusted and the server’s credentials
217 accepted without verification, or to supply a previously provided
218 thumbprint for verification.
219 --tang-url <url>
221 If creating a pool encrypted via NBDE using a tang server,
222 specifies the URL of the server.
223 --clevis <(nbde | tang | tpm2)>
225 The clevis method that should be used to encrypt the created pool.
226 --no-overprovision
228 Do not allow the pool to allocate more logical space for its
229 filesystems than it has physical space available.
230 --size <size spec>
232 Used to specify the size of, e.g., a filesystem. The specification
233 format must follow the standard size specification format for input
234 (see below).
235
237 The format of a size specification is '<magnitude><unit specifier>'
238 where the magnitude must be a decimal integer and the unit specifier
239 may be any of 'B', 'KiB', 'MiB', 'GiB', 'TiB'. or 'PiB'.
240
242 STRATIS_DBUS_TIMEOUT
243 Sets a timeout for any Stratis D-Bus call. If this environment
244 variable is not set, a default value of 120 seconds is used for the
245 timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable
246 values are:
247 1. an integer between 0 (inclusive) and 1073741823 (inclusive),
249 which represents the timeout length in milliseconds
250 2. -1, which represents the libdbus default timeout
252
254 FIELDS for stratis pool list
255 Name
257 The name of the pool.
258 Total / Used / Free
260 The physical usage statistics for the pool.
261 Properties
263 Boolean valued properties that the pool may have. Each property has
264 a two-letter camel-case code. If the pool does not have the
265 property, a ~, for negation, is prepended to the property code. If
266 the engine experienced an error when obtaining the property, a "?",
267 representing "unknown", is prepended to the property code. The
268 property codes are: Ca - indicates the pool has a cache, Cr -
269 indicates the pool is encrypted, Op - indicates the pool allows
270 overprovisioning.
271 UUID
273 The UUID of the pool.
274 Alerts
276 Any unusual or urgent information about the pool of which the user
277 should be made aware.
278 FIELDS for stratis pool list --stopped
280 Name
282 The name of the pool.
283 UUID
285 The UUID of the pool.
286 # Devices
288 The number of devices used by the pool.
289 Key Description
291 The kernel key description used by the pool.
292 Clevis
294 The status of Clevis encryption ("present" or "N/A").
295 FIELDS for stratis filesystem list
297 Pool
299 The name of the pool containing the filesystem.
300 Filesystem
302 The name of the filesystem.
303 Total / Used / Free
305 The size of the filesystem.
306 Created
308 The time the filesystem was created.
309 Device
311 The device path to use for mounting the filesystem.
312 UUID
314 The UUID of the filesystem.
315 FIELDS for stratis blockdev list
317 Pool Name
319 The name of the pool using the block device.
320 Device Node
322 The device node of the block device. A second device node will be
323 displayed in parentheses if the block device is encrypted. This
324 device node is the device node of the associated dm-crypt device.
325 Physical Size
327 The total size of the device on which stratisd places Stratis
328 metadata. If the device is encrypted, this size will be slightly
329 smaller than the total size of the device specified by the user; it
330 will be the size of the associated dm-crypt device. A second size
331 will be displayed in parentheses if stratisd has observed that the
332 device has a size that is different from the size that stratisd is
333 making use of. This can happen if, e.g., a RAID device was
334 previously added to a pool and has since been expanded.
335 Tier
337 The data tier type ("Data" or "Cache")
338 FIELDS for stratis key list
340 Key Description
342 The key description corresponding to a key in the kernel keyring
343 that that can be used for encryption.
344
346 Encryption and a cache are mutually exclusive choices. If a pool is
347 encrypted, an attempt to initialize a cache will result in an error.
348 There is a restriction on the total size of the cache device of 32 TiB.
350 Adding devices to the cache so that the cumulative size of all the
351 devices in the cache exceeds 32 TiB will result in an error.
352
354 If a block device appears to be already in use, stratisd will refuse to
355 claim it. To allow use with stratisd, any signature on the device must
356 first be erased. Please carefully verify the identity and availability
357 of the device before taking such a step.
358
360 Example 1. Creating a Stratis pool
361 stratis pool create mypool /dev/sdb /dev/sdc
363 Example 2. Creating an encrypted pool
365 stratis key set --capture-key someKeyDescription
367 stratis pool create --key-desc someKeyDescription mypool /dev/sdb
369 /dev/sdc
370 Example 3. Creating a filesystem from a pool
372 stratis filesystem create mypool data1
374 Example 4. Binding a pool’s devices to use an NBDE policy for
376 decryption
377 stratis pool bind nbde --trust-url mypool someTangServerUrl
379
381 mount(8), umount(8), fstab(5)
382
384 GitHub for issues and development
385 https://github.com/stratis-storage/project/issues
386 Mailing list
388 stratis-devel@lists.fedorahosted.org for general development
389 discussion
390 Unknown values
392 If the stratisd D-Bus API returns values that stratis-cli cannot
393 interpret, stratis-cli will substitute "???". If encountered,
394 upgrading to the latest version of stratis-cli, or filing an issue,
395 is recommended.
396 Unobtainable values
398 If the stratisd D-Bus API indicates that a value is unobtainable,
399 stratis-cli will substitute "FAILURE". This may indicate something
400 wrong with the pool, blockdev, or filesystem. In some cases,
401 restarting stratisd may resolve the issue.
402
404 stratis-cli is licensed under the Apache License, Version 2.0. Software
405 distributed under this license is distributed on an "AS IS" BASIS,
406 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
407 implied.
408 01/25/2023 STRATIS(8)