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 list
47 List all pools on the system.
48 pool rename <old_pool_name> <new_pool_name>
50 Rename a pool.
51 pool destroy <pool_name>
53 Destroy a pool and all the filesystems created from it.
54 pool add-data <pool_name> <blockdev> [<blockdev>..]
56 Add one or more blockdevs to an existing pool, to enlarge its
57 storage capacity.
58 pool init-cache <pool_name> <blockdev> [<blockdev>..]
60 Initialize a cache for an existing pool. Add one or more blockdevs
61 to a pool, to be used as cache instead of additional storage.
62 Typically, smaller and faster drives, such as SSDs, are used for
63 this purpose.
64 pool add-cache <pool_name> <blockdev> [<blockdev>..]
66 Add one or more blockdevs to an existing pool with an initialized
67 cache.
68 pool unlock <(keyring | clevis)>
70 Unlock all devices that are part of an encrypted pool registered
71 with stratisd but that have not yet been opened. The available
72 unlock methods are keyring or clevis.
73 pool bind <(nbde|tang)> <pool name> <url> <(--thumbprint <thp> |
75 --trust-url)>
76 Bind the devices in the specified pool to a supplementary
77 encryption mechanism that uses NBDE (Network-Bound Disc
78 Encryption). tang is an alias for nbde.
79 pool bind tpm2 <pool name>
81 Bind the devices in the specified pool to a supplementary
82 encryption mechanism that uses TPM 2.0 (Trusted Platform Module).
83 pool bind keyring <pool name> <keydesc>
85 Bind the devices in the specified pool to a supplementary
86 encryption mechanism using a key in the kernel keyring.
87 pool rebind clevis <pool name>
89 Rebind the devices in the spcified pool using the Clevis
90 configuration with which the devices in the pool were previously
91 bound.
92 pool rebind keyring <pool_name> <keydesc>
94 Rebind the devices in the specified pool using the specified key
95 description.
96 pool unbind <(clevis|keyring)> <pool name>
98 Unbind the devices in the specified pool from the specified
99 encryption mechanism.
100 pool set-fs-limit <pool name> <amount>
102 Set the limit on the number of file systems allowed per-pool. This
103 number may only be increased from its current value.
104 pool overprovision <pool name> <(yes|no)>
106 Set overprovisioning mode. If set to "yes", the pool may allow
107 overprovisioning, i.e, the sum of the logical sizes of the Stratis
108 filesystems supported by the pool may exceed the amount of data
109 space available.
110 pool explain <code>
112 Explain any code that might show up in the Alerts column when
113 listing a pool. Codes may be prefixed with a "W", for "warning", or
114 an "E", for "error".
115 pool debug get-object-path <(--uuid <uuid> |--name <name>)>
117 Look up the D-Bus object path for a pool given the UUID or name.
118 filesystem create <pool_name> <fs_name> [<fs_name>..] [--size <size>]
120 Create one or more filesystems from the specified pool. If --size
121 option is specified, make each filesystem the specified size.
122 Otherwise, accept the stratisd default. NOTE: There is a temporary
123 restriction on the number of filesystems that can be specified with
124 this command. Specifying more than one filesystem will result in an
125 error.
126 filesystem snapshot <pool_name> <fs_name> <snapshot_name>
128 Snapshot the filesystem in the specified pool.
129 filesystem list [pool_name]
131 List all filesystems that exist in the specified pool, or all
132 pools, if no pool name is given.
133 filesystem destroy <pool_name> <fs_name> [<fs_name>..]
135 Destroy one or more filesystems that exist in the specified pool.
136 filesystem rename <pool_name> <fs_name> <new_name>
138 Rename a filesystem.
139 filesystem debug get-object-path <(--uuid <uuid> |--name <name>)>
141 Look up the D-Bus object path for a filesystem given the UUID or
142 name.
143 blockdev list [pool_name]
145 List all blockdevs that make up the specified pool, or all pools,
146 if no pool name is given.
147 blockdev debug get-object-path <(--uuid <uuid>)>
149 Look up the D-Bus object path for a blockdev given the UUID.
150 key list
152 List all key-descriptions in the kernel keyring that can be used
153 for encryption.
154 key set <(--keyfile-path <path> | --capture-key)> <key_desc>
156 Set a key in the kernel keyring for use with encryption.
157 key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
159 Reset the key data of an existing key in the kernel keyring.
160 key unset <key_desc>
162 Unset a key in the kernel keyring so it is no longer available for
163 encryption operations.
164 report <report_name>
166 Get a report from the daemon regarding its internal state. The
167 engine_state_report name will be supported in future releases. Any
168 other report name should be considered unstable and may be removed
169 in a future release. The JSON schema of any report must always be
170 considered unstable.
171 daemon version
173 Show the Stratis service’s version.
174
176 --key-desc
177 The key description of the key that should be used to encrypt the
178 created pool. The key description must correspond to a key set in
179 the kernel keyring with the key command.
180 --keyfile-path <path> | --capture-key
182 These mutually exclusive options allow a user to specify a key used
183 for encryption in one of two ways. The --keyfile-path option
184 requires an argument, the path to a file containing the key. If the
185 --capture-key option is selected instead, the user must enter the
186 key at the ensuing prompt. The key value is terminated at the first
187 newline character that the user enters, and does not include the
188 newline character. On the other hand, if the file specified as an
189 argument for the --keyfile-path option contains a newline character
190 anywhere, the newline character will be included in the key value.
191 --thumbprint <thp> | --trust-url
193 These mutually exclusive options allow a user to specify that a
194 tang server’s URL should be trusted and the server’s credentials
195 accepted without verification, or to supply a previously provided
196 thumbprint for verification.
197 --tang-url <url>
199 If creating a pool encrypted via NBDE using a tang server,
200 specifies the URL of the server.
201 --clevis <(nbde | tang | tpm2)>
203 The clevis method that should be used to encrypt the created pool.
204 --no-overprovision
206 Do not allow the pool to allocate more logical space for its
207 filesystems than it has physical space available.
208 --size <size spec>
210 Used to specify the size of, e.g., a filesystem. The specification
211 format must follow the standard size specification format for input
212 (see below).
213
215 The format of a size specification is '<magnitude><unit specifier>'
216 where the magnitude must be a decimal integer and the unit specifier
217 may be any of 'B', 'KiB', 'MiB', 'GiB', 'TiB'. or 'PiB'.
218
220 STRATIS_DBUS_TIMEOUT
221 Sets a timeout for any Stratis D-Bus call. If this environment
222 variable is not set, a default value of 120 seconds is used for the
223 timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable
224 values are:
225 1. an integer between 0 (inclusive) and 1073741823 (inclusive),
227 which represents the timeout length in milliseconds
228 2. -1, which represents the libdbus default timeout
230
232 FIELDS for stratis pool list
233 Name
235 The name of the pool.
236 Total / Used / Free
238 The physical usage statistics for the pool.
239 Properties
241 Boolean valued properties that the pool may have. Each property has
242 a two-letter camel-case code. If the pool does not have the
243 property, a ~, for negation, is prepended to the property code. If
244 the engine experienced an error when obtaining the property, a "?",
245 representing "unknown", is prepended to the property code. The
246 property codes are: Ca - indicates the pool has a cache, Cr -
247 indicates the pool is encrypted, Op - indicates the pool allows
248 overprovisioning.
249 UUID
251 The UUID of the pool.
252 Alerts
254 Any unusual or urgent information about the pool of which the user
255 should be made aware.
256 FIELDS for stratis filesystem list
258 Pool
260 The name of the pool containing the filesystem.
261 Filesystem
263 The name of the filesystem.
264 Total / Used / Free
266 The size of the filesystem.
267 Created
269 The time the filesystem was created.
270 Device
272 The device path to use for mounting the filesystem.
273 UUID
275 The UUID of the filesystem.
276 FIELDS for stratis blockdev list
278 Pool Name
280 The name of the pool using the block device.
281 Device Node
283 The device node of the block device. A second device node will be
284 displayed in parentheses if the block device is encrypted. This
285 device node is the device node of the associated dm-crypt device.
286 Physical Size
288 The total size of the device on which stratisd places Stratis
289 metadata. If the device is encrypted, this size will be slightly
290 smaller than the total size of the device specified by the user; it
291 will be the size of the associated dm-crypt device.
292 Tier
294 The data tier type ("Data" or "Cache")
295 FIELDS for stratis key list
297 Key Description
299 The key description corresponding to a key in the kernel keyring
300 that that can be used for encryption.
301
303 Encryption and a cache are mutually exclusive choices. If a pool is
304 encrypted, an attempt to initialize a cache will result in an error.
305 There is a restriction on the total size of the cache device of 32 TiB.
307 Adding devices to the cache so that the cumulative size of all the
308 devices in the cache exceeds 32 TiB will result in an error.
309
311 If a block device appears to be already in use, stratisd will refuse to
312 claim it. To allow use with stratisd, any signature on the device must
313 first be erased. Please carefully verify the identity and availability
314 of the device before taking such a step.
315
317 Example 1. Creating a Stratis pool
318 stratis pool create mypool /dev/sdb /dev/sdc
320 Example 2. Creating an encrypted pool
322 stratis key set --capture-key someKeyDescription
324 stratis pool create --key-desc someKeyDescription mypool /dev/sdb
326 /dev/sdc
327 Example 3. Creating a filesystem from a pool
329 stratis filesystem create mypool data1
331 Example 4. Binding a pool’s devices to use an NBDE policy for
333 decryption
334 stratis pool bind nbde --trust-url mypool someTangServerUrl
336
338 mount(8), umount(8), fstab(5)
339
341 GitHub for issues and development
342 https://github.com/stratis-storage/project/issues
343 Mailing list
345 stratis-devel@lists.fedorahosted.org for general development
346 discussion
347 Unknown values
349 If the stratisd D-Bus API returns values that stratis-cli cannot
350 interpret, stratis-cli will substitute "???". If encountered,
351 upgrading to the latest version of stratis-cli, or filing an issue,
352 is recommended.
353 Unobtainable values
355 If the stratisd D-Bus API indicates that a value is unobtainable,
356 stratis-cli will substitute "FAILURE". This may indicate something
357 wrong with the pool, blockdev, or filesystem. In some cases,
358 restarting stratisd may resolve the issue.
359
361 stratis-cli is licensed under the Apache License, Version 2.0. Software
362 distributed under this license is distributed on an "AS IS" BASIS,
363 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
364 implied.
365 06/07/2022 STRATIS(8)