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 <redundancy|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 [--redundancy <redundancy>] [--key-desc <key_desc>]
41       [--clevis <(nbde|tang|tpm2)> [--tang-url <tang_url>] [<(--thumbprint
42       <thp> | --trust-url)>] <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 unbind <(clevis|keyring)> <pool name>
89           Unbind the devices in the specified pool from the specified
90           encryption mechanism.
91
92       filesystem create <pool_name> <fs_name> [<fs_name>..]
93           Create one or more filesystems from the specified pool. NOTE: There
94           is a temporary restriction on the number of filesystems that can be
95           specified with this command. Specifying more than one filesystem
96           will result in an error.
97
98       filesystem snapshot <pool_name> <fs_name> <snapshot_name>
99           Snapshot the filesystem in the specified pool.
100
101       filesystem list [pool_name]
102           List all filesystems that exist in the specified pool, or all
103           pools, if no pool name is given.
104
105       filesystem destroy <pool_name> <fs_name> [<fs_name>..]
106           Destroy one or more filesystems that exist in the specified pool.
107
108       filesystem rename <pool_name> <fs_name> <new_name>
109           Rename a filesystem.
110
111       blockdev list [pool_name]
112           List all blockdevs that make up the specified pool, or all pools,
113           if no pool name is given.
114
115       key list
116           List all key-descriptions in the kernel keyring that can be used
117           for encryption.
118
119       key set <(--keyfile-path <path> | --capture-key)> <key_desc>
120           Set a key in the kernel keyring for use with encryption.
121
122       key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
123           Reset the key data of an existing key in the kernel keyring.
124
125       key unset <key_desc>
126           Unset a key in the kernel keyring so it is no longer available for
127           encryption operations.
128
129       report <report_name>
130           Get a report from the daemon regarding its internal state. The
131           engine_state_report name will be supported in future releases. Any
132           other report name should be considered unstable and may be removed
133           in a future release. The JSON schema of any report must always be
134           considered unstable.
135
136       daemon redundancy
137           List the redundancy levels that the Stratis service supports.
138
139       daemon version
140           Show the Stratis service’s version.
141

OPTIONS

143       --redundancy
144           The redundancy for the created pool. The only option is "none"
145           which is also the default.
146
147       --key-desc
148           The key description of the key that should be used to encrypt the
149           created pool. The key description must correspond to a key set in
150           the kernel keyring with the key command.
151
152       --keyfile-path <path> | --capture-key
153           These mutually exclusive options allow a user to specify a key used
154           for encryption in one of two ways. The --keyfile-path option
155           requires an argument, the path to a file containing the key. If the
156           --capture-key option is selected instead, the user must enter the
157           key at the ensuing prompt. The key value is terminated at the first
158           newline character that the user enters, and does not include the
159           newline character. On the other hand, if the file specified as an
160           argument for the --keyfile-path option contains a newline character
161           anywhere, the newline character will be included in the key value.
162
163       --thumbprint <thp> | --trust-url
164           These mutually exclusive options allow a user to specify that a
165           tang server’s URL should be trusted and the server’s credentials
166           accepted without verification, or to supply a previously provided
167           thumbprint for verification.
168
169       --tang-url <url>
170           If creating a pool encrypted via NBDE using a tang server,
171           specifies the URL of the server.
172
173       --clevis <(nbde | tang | tpm2)>
174           The clevis method that should be used to encrypt the created pool.
175

ENVIRONMENT VARIABLES

177       STRATIS_DBUS_TIMEOUT
178           Sets a timeout for any Stratis D-Bus call. If this environment
179           variable is not set, a default value of 120 seconds is used for the
180           timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable
181           values are:
182
183            1. an integer between 0 (inclusive) and 1073741823 (inclusive),
184               which represents the timeout length in milliseconds
185
186            2. -1, which represents the libdbus default timeout
187

LIST OUTPUT FIELDS

189       FIELDS for stratis pool list
190
191       Name
192           The name of the pool.
193
194       Total Physical
195           The physical usage statistics for the pool (Total / Used / Free).
196
197       Properties
198           Boolean valued properties that the pool may have. Each property has
199           a two-letter camel-case code. If the pool does not have the
200           property, a ~, for negation, is prepended to the property code. If
201           the engine experienced an error when obtaining the property, a "?",
202           representing "unknown", is prepended to the property code. The
203           property codes are: Ca - indicates the pool has a cache, Cr -
204           indicates the pool is encrypted.
205
206       FIELDS for stratis filesystem list
207
208       Pool Name
209           The name of the pool containing the filesystem.
210
211       Used
212           The amount of storage space used in the pool by this filesystem.
213
214       Created
215           The time the filesystem was created.
216
217       Device
218           The device path to use for mounting the filesystem.
219
220       UUID
221           The UUID of the filesystem.
222
223       FIELDS for stratis blockdev list
224
225       Pool Name
226           The name of the pool using the block device.
227
228       Device Node
229           The device node of the block device. A second device node will be
230           displayed in parentheses if the block device is encrypted. This
231           device node is the device node of the associated dm-crypt device.
232
233       Physical Size
234           The total size of the device on which stratisd places Stratis
235           metadata. If the device is encrypted, this size will be slightly
236           smaller than the total size of the device specified by the user; it
237           will be the size of the associated dm-crypt device.
238
239       Tier
240           The data tier type ("Data" or "Cache")
241
242       FIELDS for stratis key list
243
244       Key Description
245           The key description corresponding to a key in the kernel keyring
246           that that can be used for encryption.
247

RESTRICTIONS

249       Encryption and a cache are mutually exclusive choices. If a pool is
250       encrypted, an attempt to initialize a cache will result in an error.
251
252       There is a restriction on the total size of the cache device of 32 TiB.
253       Adding devices to the cache so that the cumulative size of all the
254       devices in the cache exceeds 32 TiB will result in an error.
255

NOTES

257       If a block device appears to be already in use, stratisd will refuse to
258       claim it. To allow use with stratisd, any signature on the device must
259       first be erased. Please carefully verify the identity and availability
260       of the device before taking such a step.
261

EXAMPLES

263       Example 1. Creating a Stratis pool
264
265       stratis pool create mypool /dev/sdb /dev/sdc
266
267       Example 2. Creating an encrypted pool
268
269       stratis key set --capture-key someKeyDescription
270
271       stratis pool create --key-desc someKeyDescription mypool /dev/sdb
272       /dev/sdc
273
274       Example 3. Creating a filesystem from a pool
275
276       stratis filesystem create mypool data1
277
278       Example 4. Binding a pool’s devices to use an NBDE policy for
279       decryption
280
281       stratis pool bind nbde --trust-url mypool someTangServerUrl
282

SEE ALSO

284       mount(8), umount(8), fstab(5)
285

REPORTING BUGS & DEVELOPMENT

287       GitHub for issues and development
288           https://github.com/stratis-storage, against either stratis-cli or
289           stratisd projects, based on likelihood of issue being with the
290           command-line tool or the service daemon.
291
292       Mailing list
293           stratis-devel@lists.fedorahosted.org for general development
294           discussion
295
296       Unknown values
297           If the stratisd D-Bus API returns values that stratis-cli cannot
298           interpret, stratis-cli will substitute "???". If encountered,
299           upgrading to the latest version of stratis-cli, or filing an issue,
300           is recommended.
301
302       Unobtainable values
303           If the stratisd D-Bus API indicates that a value is unobtainable,
304           stratis-cli will substitute "FAILURE". This may indicate something
305           wrong with the pool, blockdev, or filesystem. In some cases,
306           restarting stratisd may resolve the issue.
307

LICENSE

309       stratis-cli is licensed under the Apache License, Version 2.0. Software
310       distributed under this license is distributed on an "AS IS" BASIS,
311       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
312       implied.
313
314
315
316                                  05/20/2021                        STRATIS(8)
Impressum