1STRATIS(8)                                                          STRATIS(8)
2
3
4

NAME

6       stratis - Configure Stratis local storage pools
7

SYNOPSIS

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

DESCRIPTION

17       stratis is a command-line tool to create, modify, and destroy Stratis
18       pools, and the filesystems allocated from the pool.
19
20       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

GLOBAL OPTIONS

25       --version
26           Show stratis-cli version.
27
28       --help, -h
29           Show help on command.
30
31       --propagate
32           (For debugging.) Allow exceptions raised during execution to
33           propagate.
34
35       --unhyphenated-uuids
36           (For listing.) Print pool and filesystem UUIDs without hyphens for
37           list commands.
38

COMMANDS

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
46       pool list
47           List all pools on the system.
48
49       pool rename <old_pool_name> <new_pool_name>
50           Rename a pool.
51
52       pool destroy <pool_name>
53           Destroy a pool and all the filesystems created from it.
54
55       pool add-data <pool_name> <blockdev> [<blockdev>..]
56           Add one or more blockdevs to an existing pool, to enlarge its
57           storage capacity.
58
59       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
65       pool add-cache <pool_name> <blockdev> [<blockdev>..]
66           Add one or more blockdevs to an existing pool with an initialized
67           cache.
68
69       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
74       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
80       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
84       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
88       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
93       pool rebind keyring <pool_name> <keydesc>
94           Rebind the devices in the specified pool using the specified key
95           description.
96
97       pool unbind <(clevis|keyring)> <pool name>
98           Unbind the devices in the specified pool from the specified
99           encryption mechanism.
100
101       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
105       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
111       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
116       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
119       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
127       filesystem snapshot <pool_name> <fs_name> <snapshot_name>
128           Snapshot the filesystem in the specified pool.
129
130       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
134       filesystem destroy <pool_name> <fs_name> [<fs_name>..]
135           Destroy one or more filesystems that exist in the specified pool.
136
137       filesystem rename <pool_name> <fs_name> <new_name>
138           Rename a filesystem.
139
140       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
144       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
148       blockdev debug get-object-path <(--uuid <uuid>)>
149           Look up the D-Bus object path for a blockdev given the UUID.
150
151       key list
152           List all key-descriptions in the kernel keyring that can be used
153           for encryption.
154
155       key set <(--keyfile-path <path> | --capture-key)> <key_desc>
156           Set a key in the kernel keyring for use with encryption.
157
158       key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
159           Reset the key data of an existing key in the kernel keyring.
160
161       key unset <key_desc>
162           Unset a key in the kernel keyring so it is no longer available for
163           encryption operations.
164
165       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
172       daemon version
173           Show the Stratis service’s version.
174

OPTIONS

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
181       --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
192       --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
198       --tang-url <url>
199           If creating a pool encrypted via NBDE using a tang server,
200           specifies the URL of the server.
201
202       --clevis <(nbde | tang | tpm2)>
203           The clevis method that should be used to encrypt the created pool.
204
205       --no-overprovision
206           Do not allow the pool to allocate more logical space for its
207           filesystems than it has physical space available.
208
209       --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

SIZE SPECIFICATION FORMAT FOR INPUT

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

ENVIRONMENT VARIABLES

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
226            1. an integer between 0 (inclusive) and 1073741823 (inclusive),
227               which represents the timeout length in milliseconds
228
229            2. -1, which represents the libdbus default timeout
230

LIST OUTPUT FIELDS

232       FIELDS for stratis pool list
233
234       Name
235           The name of the pool.
236
237       Total / Used / Free
238           The physical usage statistics for the pool.
239
240       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
250       UUID
251           The UUID of the pool.
252
253       Alerts
254           Any unusual or urgent information about the pool of which the user
255           should be made aware.
256
257       FIELDS for stratis filesystem list
258
259       Pool
260           The name of the pool containing the filesystem.
261
262       Filesystem
263           The name of the filesystem.
264
265       Total / Used / Free
266           The size of the filesystem.
267
268       Created
269           The time the filesystem was created.
270
271       Device
272           The device path to use for mounting the filesystem.
273
274       UUID
275           The UUID of the filesystem.
276
277       FIELDS for stratis blockdev list
278
279       Pool Name
280           The name of the pool using the block device.
281
282       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
287       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
293       Tier
294           The data tier type ("Data" or "Cache")
295
296       FIELDS for stratis key list
297
298       Key Description
299           The key description corresponding to a key in the kernel keyring
300           that that can be used for encryption.
301

RESTRICTIONS

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
306       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

NOTES

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

EXAMPLES

317       Example 1. Creating a Stratis pool
318
319       stratis pool create mypool /dev/sdb /dev/sdc
320
321       Example 2. Creating an encrypted pool
322
323       stratis key set --capture-key someKeyDescription
324
325       stratis pool create --key-desc someKeyDescription mypool /dev/sdb
326       /dev/sdc
327
328       Example 3. Creating a filesystem from a pool
329
330       stratis filesystem create mypool data1
331
332       Example 4. Binding a pool’s devices to use an NBDE policy for
333       decryption
334
335       stratis pool bind nbde --trust-url mypool someTangServerUrl
336

SEE ALSO

338       mount(8), umount(8), fstab(5)
339

REPORTING BUGS & DEVELOPMENT

341       GitHub for issues and development
342           https://github.com/stratis-storage/project/issues
343
344       Mailing list
345           stratis-devel@lists.fedorahosted.org for general development
346           discussion
347
348       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
354       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

LICENSE

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
366
367
368                                  06/07/2022                        STRATIS(8)
Impressum