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 <redundancy|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 [--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 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 unbind <(clevis|keyring)> <pool name>
89 Unbind the devices in the specified pool from the specified
90 encryption mechanism.
91 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 filesystem snapshot <pool_name> <fs_name> <snapshot_name>
99 Snapshot the filesystem in the specified pool.
100 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 filesystem destroy <pool_name> <fs_name> [<fs_name>..]
106 Destroy one or more filesystems that exist in the specified pool.
107 filesystem rename <pool_name> <fs_name> <new_name>
109 Rename a filesystem.
110 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 key list
116 List all key-descriptions in the kernel keyring that can be used
117 for encryption.
118 key set <(--keyfile-path <path> | --capture-key)> <key_desc>
120 Set a key in the kernel keyring for use with encryption.
121 key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
123 Reset the key data of an existing key in the kernel keyring.
124 key unset <key_desc>
126 Unset a key in the kernel keyring so it is no longer available for
127 encryption operations.
128 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 daemon redundancy
137 List the redundancy levels that the Stratis service supports.
138 daemon version
140 Show the Stratis service’s version.
141
143 --redundancy
144 The redundancy for the created pool. The only option is "none"
145 which is also the default.
146 --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 --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 --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 --tang-url <url>
170 If creating a pool encrypted via NBDE using a tang server,
171 specifies the URL of the server.
172 --clevis <(nbde | tang | tpm2)>
174 The clevis method that should be used to encrypt the created pool.
175
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 1. an integer between 0 (inclusive) and 1073741823 (inclusive),
184 which represents the timeout length in milliseconds
185 2. -1, which represents the libdbus default timeout
187
189 FIELDS for stratis pool list
190 Name
192 The name of the pool.
193 Total Physical
195 The physical usage statistics for the pool (Total / Used / Free).
196 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 UUID
207 The UUID of the pool.
208 FIELDS for stratis filesystem list
210 Pool Name
212 The name of the pool containing the filesystem.
213 Used
215 The amount of storage space used in the pool by this filesystem.
216 Created
218 The time the filesystem was created.
219 Device
221 The device path to use for mounting the filesystem.
222 UUID
224 The UUID of the filesystem.
225 FIELDS for stratis blockdev list
227 Pool Name
229 The name of the pool using the block device.
230 Device Node
232 The device node of the block device. A second device node will be
233 displayed in parentheses if the block device is encrypted. This
234 device node is the device node of the associated dm-crypt device.
235 Physical Size
237 The total size of the device on which stratisd places Stratis
238 metadata. If the device is encrypted, this size will be slightly
239 smaller than the total size of the device specified by the user; it
240 will be the size of the associated dm-crypt device.
241 Tier
243 The data tier type ("Data" or "Cache")
244 FIELDS for stratis key list
246 Key Description
248 The key description corresponding to a key in the kernel keyring
249 that that can be used for encryption.
250
252 Encryption and a cache are mutually exclusive choices. If a pool is
253 encrypted, an attempt to initialize a cache will result in an error.
254 There is a restriction on the total size of the cache device of 32 TiB.
256 Adding devices to the cache so that the cumulative size of all the
257 devices in the cache exceeds 32 TiB will result in an error.
258
260 If a block device appears to be already in use, stratisd will refuse to
261 claim it. To allow use with stratisd, any signature on the device must
262 first be erased. Please carefully verify the identity and availability
263 of the device before taking such a step.
264
266 Example 1. Creating a Stratis pool
267 stratis pool create mypool /dev/sdb /dev/sdc
269 Example 2. Creating an encrypted pool
271 stratis key set --capture-key someKeyDescription
273 stratis pool create --key-desc someKeyDescription mypool /dev/sdb
275 /dev/sdc
276 Example 3. Creating a filesystem from a pool
278 stratis filesystem create mypool data1
280 Example 4. Binding a pool’s devices to use an NBDE policy for
282 decryption
283 stratis pool bind nbde --trust-url mypool someTangServerUrl
285
287 mount(8), umount(8), fstab(5)
288
290 GitHub for issues and development
291 https://github.com/stratis-storage, against either stratis-cli or
292 stratisd projects, based on likelihood of issue being with the
293 command-line tool or the service daemon.
294 Mailing list
296 stratis-devel@lists.fedorahosted.org for general development
297 discussion
298 Unknown values
300 If the stratisd D-Bus API returns values that stratis-cli cannot
301 interpret, stratis-cli will substitute "???". If encountered,
302 upgrading to the latest version of stratis-cli, or filing an issue,
303 is recommended.
304 Unobtainable values
306 If the stratisd D-Bus API indicates that a value is unobtainable,
307 stratis-cli will substitute "FAILURE". This may indicate something
308 wrong with the pool, blockdev, or filesystem. In some cases,
309 restarting stratisd may resolve the issue.
310
312 stratis-cli is licensed under the Apache License, Version 2.0. Software
313 distributed under this license is distributed on an "AS IS" BASIS,
314 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
315 implied.
316 08/05/2021 STRATIS(8)