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
36 pool create [--redundancy <redundancy>] [--key-desc <key_desc>]
37 <pool_name> <blockdev> [<blockdev>..]
38 Create a pool from one or more block devices, with the given pool
39 name.
40 pool list
42 List all pools on the system.
43 pool rename <old_pool_name> <new_pool_name>
45 Rename a pool.
46 pool destroy <pool_name>
48 Destroy a pool and all the filesystems created from it.
49 pool add-data <pool_name> <blockdev> [<blockdev>..]
51 Add one or more blockdevs to an existing pool, to enlarge its
52 storage capacity.
53 pool init-cache <pool_name> <blockdev> [<blockdev>..]
55 Initialize a cache for an existing pool. Add one or more blockdevs
56 to a pool, to be used as cache instead of additional storage.
57 Typically, smaller and faster drives, such as SSDs, are used for
58 this purpose.
59 pool add-cache <pool_name> <blockdev> [<blockdev>..]
61 Add one or more blockdevs to an existing pool with an initialized
62 cache.
63 pool unlock
65 Unlock all devices that are part of an encrypted pool registered
66 with stratisd but that have not yet been opened.
67 filesystem create <pool_name> <fs_name> [<fs_name>..]
69 Create one or more filesystems from the specified pool. NOTE: There
70 is a temporary restriction on the number of filesystems that can be
71 specified with this command. Specifying more than one filesystem
72 will result in an error.
73 filesystem snapshot <pool_name> <fs_name> <snapshot_name>
75 Snapshot the filesystem in the specified pool.
76 filesystem list [pool_name]
78 List all filesystems that exist in the specified pool, or all
79 pools, if no pool name is given.
80 filesystem destroy <pool_name> <fs_name> [<fs_name>..]
82 Destroy one or more filesystems that exist in the specified pool.
83 filesystem rename <pool_name> <fs_name> <new_name>
85 Rename a filesystem.
86 blockdev list [pool_name]
88 List all blockdevs that make up the specified pool, or all pools,
89 if no pool name is given.
90 key set <(--keyfile-path <path> | --capture-key)> <key_desc>
92 Set a key in the kernel keyring for use with encryption.
93 key reset <(--keyfile-path <path> | --capture-key)> <key_desc>
95 Reset the key data of an existing key in the kernel keyring.
96 key unset <key_desc>
98 Unset a key in the kernel keyring so it is no longer available for
99 encryption operations.
100 report <report_name>
102 Get a report from the daemon regarding its internal state. This
103 command is not supported as the report names and returned JSON
104 schemas are unstable and may be changed at any time.
105 daemon redundancy
107 List the redundancy levels that the Stratis service supports.
108 daemon version
110 Show the Stratis service’s version.
111
113 --redundancy
114 The redundancy for the created pool. The only option is "none"
115 which is also the default.
116 --key-desc
118 The key description of the key that should be used to encrypt the
119 created pool. The key description must correspond to a key set in
120 the kernel keyring with the key command.
121 --keyfile-path <path> | --capture-key
123 These mutually exclusive options allow a user to specify a key used
124 for encryption in one of two ways. The --keyfile-path option
125 requires an argument, the path to a file containing the key. If the
126 --capture-key option is selected instead, the user must enter the
127 key at the ensuing prompt. The key value is terminated at the first
128 newline character that the user enters, and does not include the
129 newline character. On the other hand, if the file specified as an
130 argument for the --keyfile-path option contains a newline character
131 anywhere, the newline character will be included in the key value.
132
134 STRATIS_DBUS_TIMEOUT
135 Sets a timeout for any Stratis D-Bus call. If this environment
136 variable is not set, a default value of 120 seconds is used for the
137 timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable
138 values are:
139 1. an integer between 0 (inclusive) and 1073741823 (inclusive),
141 which represents the timeout length in milliseconds
142 2. -1, which represents the libdbus default timeout
144
146 FIELDS for stratis pool list
147 Name
149 The name of the pool.
150 Total Physical
152 The physical usage statistics for the pool (Total / Used / Free).
153 Properties
155 Boolean valued properties that the pool may have. Each property has
156 a two-letter camel-case code. If the pool does not have the
157 property, a ~, for negation, is prepended to the property code. If
158 the engine experienced an error when obtaining the property, a "?",
159 representing "unknown", is prepended to the property code. The
160 property codes are: Ca - indicates the pool has a cache, Cr -
161 indicates the pool is encrypted.
162 FIELDS for stratis filesystem list
164 Pool Name
166 The name of the pool containing the filesystem.
167 Used
169 The amount of storage space used in the pool by this filesystem.
170 Created
172 The time the filesystem was created.
173 Device
175 The device path to use for mounting the filesystem.
176 UUID
178 The UUID of the filesystem.
179 FIELDS for stratis blockdev list
181 Pool Name
183 The name of the pool using the block device.
184 Device Node
186 The device node of the block device.
187 Physical Size
189 The size of the device.
190 Tier
192 The data tier type ("Data" or "Cache")
193 FIELDS for stratis key list
195 Key Description
197 The key description corresponding to a key in the kernel keyring
198 that that can be used for encryption.
199
201 Encryption and a cache are mutually exclusive choices. If a pool is
202 encrypted, an attempt to initialize a cache will result in an error.
203 There is a restriction on the total size of the cache device of 32 TiB.
205 Adding devices to the cache so that the cumulative size of all the
206 devices in the cache exceeds 32 TiB will result in an error.
207
209 If a block device appears to be already in use, stratisd will refuse to
210 claim it. To allow use with stratisd, any signature on the device must
211 first be erased. Please carefully verify the identity and availability
212 of the device before taking such a step.
213
215 Example 1. Creating a Stratis pool
216 stratis pool create mypool /dev/sdb /dev/sdc
218 Example 2. Creating an encrypted pool
220 stratis key set --capture-key someKeyDescription
222 stratis pool create --key-desc someKeyDescription mypool /dev/sdb
224 /dev/sdc
225 Example 3. Creating a filesystem from a pool
227 stratis filesystem create mypool data1
229
231 mount(8), umount(8), fstab(5)
232
234 GitHub for issues and development
235 https://github.com/stratis-storage, against either stratis-cli or
236 stratisd projects, based on likelihood of issue being with the
237 command-line tool or the service daemon.
238 Mailing list
240 stratis-devel@lists.fedorahosted.org for general development
241 discussion
242 Unknown values
244 If the stratisd D-Bus API returns values that stratis-cli cannot
245 interpret, stratis-cli will substitute "???". If encountered,
246 upgrading to the latest version of stratis-cli, or filing an issue,
247 is recommended.
248 Unobtainable values
250 If the stratisd D-Bus API indicates that a value is unobtainable,
251 stratis-cli will substitute "FAILURE". This may indicate something
252 wrong with the pool, blockdev, or filesystem. In some cases,
253 restarting stratisd may resolve the issue.
254
256 stratis-cli is licensed under the Apache License, Version 2.0. Software
257 distributed under this license is distributed on an "AS IS" BASIS,
258 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or
259 implied.
260 07/29/2020 STRATIS(8)