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 <(--uuid <uuid> |--name <name>)>
47 Stop a pool, specifying the pool by its UUID or by its name. Tear
48 down the storage stack but leave all metadata intact.
49 pool start <(--uuid <uuid> |--name <name>)> --unlock-method <(keyring |
51 clevis)>
52 Start a pool, specifying 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 specified 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 [--size-limit <size_limit>]
137 Create one or more filesystems from the specified pool. If the
138 --size option is specified, make each filesystem the specified
139 size. Otherwise, accept the stratisd default. if the --size-limit
140 option is specified, set the filesystem’s size limit on creation.
141 If the size limit is not set, the filesystem will be grown, as
142 needed, up to the maximum possible size. The filesystem size limit
143 must be at least as large as the filesystem size. NOTE: There is a
144 temporary restriction on the number of filesystems that can be
145 specified with this command. Specifying more than one filesystem
146 will result in an error.
147 filesystem snapshot <pool_name> <fs_name> <snapshot_name>
149 Snapshot the filesystem in the specified pool.
150 filesystem list [pool_name]
152 List all filesystems that exist in the specified pool, or all
153 pools, if no pool name is given.
154 filesystem destroy <pool_name> <fs_name> [<fs_name>..]
156 Destroy one or more filesystems that exist in the specified pool.
157 filesystem rename <pool_name> <fs_name> <new_name>
159 Rename a filesystem.
160 filesystem set-size-limit <pool_name> <fs_name> <size_limit>
162 Set the filesystem size limit. Must be at least as large as the
163 filesystem’s current size. To set the size limit to the same value
164 as the filesystem’s current size, use the keyword "current".
165 filesystem unset-size-limit <pool_name> <fs_name>
167 Remove a filesystem size limit previously set.
168 filesystem debug get-object-path <(--uuid <uuid> |--name <name>)>
170 Look up the D-Bus object path for a filesystem given the UUID or
171 name.
172 blockdev list [pool_name]
174 List all blockdevs that make up the specified pool, or all pools,
175 if no pool name is given.
176 blockdev debug get-object-path <(--uuid <uuid>)>
178 Look up the D-Bus object path for a blockdev given the UUID.
179 key list
181 List all key-descriptions in the kernel keyring that can be used
182 for encryption.
183 key set <(--keyfile-path <path> | --capture-key)> <key_desc>
185 Set a key in the kernel keyring for use with encryption.
186 key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
188 Reset the key data of an existing key in the kernel keyring.
189 key unset <key_desc>
191 Unset a key in the kernel keyring so it is no longer available for
192 encryption operations.
193 report <report_name>
195 Get a report from the daemon regarding its internal state. The
196 engine_state_report name will be supported in future releases. Any
197 other report name should be considered unstable and may be removed
198 in a future release. The JSON schema of any report must always be
199 considered unstable.
200 daemon version
202 Show the Stratis service’s version.
203 debug refresh
205 For all pools that are not stopped, rebuild their storage stacks
206 from the pool-level metadata stored on each pool’s devices. This is
207 not a standard administrative command; it is intended for
208 trouble-shooting and repair only.
209
211 --key-desc
212 The key description of the key that should be used to encrypt the
213 created pool. The key description must correspond to a key set in
214 the kernel keyring with the key command.
215 --keyfile-path <path> | --capture-key
217 These mutually exclusive options allow a user to specify a key used
218 for encryption in one of two ways. The --keyfile-path option
219 requires an argument, the path to a file containing the key. If the
220 --capture-key option is selected instead, the user must enter the
221 key at the ensuing prompt. The key value is terminated at the first
222 newline character that the user enters, and does not include the
223 newline character. On the other hand, if the file specified as an
224 argument for the --keyfile-path option contains a newline character
225 anywhere, the newline character will be included in the key value.
226 --thumbprint <thp> | --trust-url
228 These mutually exclusive options allow a user to specify that a
229 tang server’s URL should be trusted and the server’s credentials
230 accepted without verification, or to supply a previously provided
231 thumbprint for verification.
232 --tang-url <url>
234 If creating a pool encrypted via NBDE using a tang server,
235 specifies the URL of the server.
236 --clevis <(nbde | tang | tpm2)>
238 The clevis method that should be used to encrypt the created pool.
239 --no-overprovision
241 Do not allow the pool to allocate more logical space for its
242 filesystems than it has physical space available.
243 --size <size spec>
245 Used to specify the size of, e.g., a filesystem. The specification
246 format must follow the standard size specification format for input
247 (see below).
248
250 The format of a size specification is '<magnitude><unit specifier>'
251 where the magnitude must be a decimal integer and the unit specifier
252 may be any of 'B', 'KiB', 'MiB', 'GiB', 'TiB'. or 'PiB'.
253
255 STRATIS_DBUS_TIMEOUT
256 Sets a timeout for any Stratis D-Bus call. If this environment
257 variable is not set, a default value of 120 seconds is used for the
258 timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable
259 values are:
260 1. an integer between 0 (inclusive) and 1073741823 (inclusive),
262 which represents the timeout length in milliseconds
263 2. -1, which represents the libdbus default timeout
265
267 FIELDS for stratis pool list
268 Name
270 The name of the pool.
271 Total / Used / Free
273 The physical usage statistics for the pool.
274 Properties
276 Boolean valued properties that the pool may have. Each property has
277 a two-letter camel-case code. If the pool does not have the
278 property, a ~, for negation, is prepended to the property code. If
279 the engine experienced an error when obtaining the property, a "?",
280 representing "unknown", is prepended to the property code. The
281 property codes are: Ca - indicates the pool has a cache, Cr -
282 indicates the pool is encrypted, Op - indicates the pool allows
283 overprovisioning.
284 UUID
286 The UUID of the pool.
287 Alerts
289 Any unusual or urgent information about the pool of which the user
290 should be made aware.
291 FIELDS for stratis pool list --stopped
293 Name
295 The name of the pool.
296 UUID
298 The UUID of the pool.
299 # Devices
301 The number of devices used by the pool.
302 Key Description
304 The kernel key description used by the pool.
305 Clevis
307 The status of Clevis encryption ("present" or "N/A").
308 FIELDS for stratis filesystem list
310 Pool
312 The name of the pool containing the filesystem.
313 Filesystem
315 The name of the filesystem.
316 Total / Used / Free
318 The size of the filesystem.
319 Created
321 The time the filesystem was created.
322 Device
324 The device path to use for mounting the filesystem.
325 UUID
327 The UUID of the filesystem.
328 FIELDS for stratis blockdev list
330 Pool Name
332 The name of the pool using the block device.
333 Device Node
335 The device node of the block device. A second device node will be
336 displayed in parentheses if the block device is encrypted. This
337 device node is the device node of the associated dm-crypt device.
338 Physical Size
340 The total size of the device on which stratisd places Stratis
341 metadata. If the device is encrypted, this size will be slightly
342 smaller than the total size of the device specified by the user; it
343 will be the size of the associated dm-crypt device. A second size
344 will be displayed in parentheses if stratisd has observed that the
345 device has a size that is different from the size that stratisd is
346 making use of. This can happen if, e.g., a RAID device was
347 previously added to a pool and has since been expanded.
348 Tier
350 The data tier type ("Data" or "Cache")
351 UUID
353 The UUID of the block device.
354 FIELDS for stratis key list
356 Key Description
358 The key description corresponding to a key in the kernel keyring
359 that that can be used for encryption.
360
362 Encryption and a cache are mutually exclusive choices. If a pool is
363 encrypted, an attempt to initialize a cache will result in an error.
364 There is a restriction on the total size of the cache device of 32 TiB.
366 Adding devices to the cache so that the cumulative size of all the
367 devices in the cache exceeds 32 TiB will result in an error.
368
370 If a block device appears to be already in use, stratisd will refuse to
371 claim it. To allow use with stratisd, any signature on the device must
372 first be erased. Please carefully verify the identity and availability
373 of the device before taking such a step.
374
376 Example 1. Creating a Stratis pool
377 stratis pool create mypool /dev/sdb /dev/sdc
379 Example 2. Creating an encrypted pool
381 stratis key set --capture-key someKeyDescription
383 stratis pool create --key-desc someKeyDescription mypool /dev/sdb
385 /dev/sdc
386 Example 3. Creating a filesystem from a pool
388 stratis filesystem create mypool data1
390 Example 4. Binding a pool’s devices to use an NBDE policy for
392 decryption
393 stratis pool bind nbde --trust-url mypool someTangServerUrl
395
397 mount(8), umount(8), fstab(5)
398
400 GitHub for issues and development
401 https://github.com/stratis-storage/project/issues
402 Mailing list
404 stratis-devel@lists.fedorahosted.org for general development
405 discussion
406 Unknown values
408 If the stratisd D-Bus API returns values that stratis-cli cannot
409 interpret, stratis-cli will substitute "???". If encountered,
410 upgrading to the latest version of stratis-cli, or filing an issue,
411 is recommended.
412 Unobtainable values
414 If the stratisd D-Bus API indicates that a value is unobtainable,
415 stratis-cli will substitute "FAILURE". This may indicate something
416 wrong with the pool, blockdev, or filesystem. In some cases,
417 restarting stratisd may resolve the issue.
418
420 stratis-cli is licensed under the Apache License, Version 2.0. Software
421 distributed under this license is distributed on an "AS IS" BASIS,
422 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
423 implied.
424 10/26/2023 STRATIS(8)