NAME¶
stratis - Configure Stratis local storage pools
SYNOPSIS¶
stratis [GLOBAL OPTIONS] pool <command> [args] [COMMAND OPTIONS]
stratis [GLOBAL OPTIONS] filesystem|fs <command> [args] [COMMAND OPTIONS]
stratis [GLOBAL OPTIONS] blockdev <command> [args] [COMMAND OPTIONS]
stratis [GLOBAL OPTIONS] key <command> [args] [COMMAND OPTIONS]
stratis [GLOBAL OPTIONS] report <report_name>
stratis [GLOBAL OPTIONS] daemon <version>
DESCRIPTION¶
stratis is a command-line tool to create, modify, and
destroy Stratis pools, and the filesystems allocated from the pool.
Stratis creates a pool from one or more block devices
(blockdevs), and then enables multiple filesystems to be
created from the pool. The user can set keys for use with pool
encryption.
GLOBAL OPTIONS¶
--version
Show stratis-cli version.
--help, -h
Show help on command.
--propagate
(For debugging.) Allow exceptions raised during execution
to propagate.
--unhyphenated-uuids
(For listing.) Print pool and filesystem UUIDs without
hyphens for list commands.
COMMANDS¶
pool create [--key-desc <key_desc>] [--clevis
<(nbde|tang|tpm2)> [--tang-url <tang_url>] [<(--thumbprint
<thp> | --trust-url)>] [--no-overprovision] <pool_name>
<blockdev> [<blockdev>..]
Create a pool from one or more block devices, with the
given pool name.
pool stop <(--uuid <uuid> |--name <name>)>
Stop a pool, specifying the pool by its UUID or by its
name. Tear down the storage stack but leave all metadata intact.
pool start <(--uuid <uuid> |--name <name>)>
--unlock-method <(keyring | clevis)>
Start a pool, specifying the pool by its UUID or by its
name. Use the --unlock-method option to specify method of unlocking the pool
if it is encrypted.
pool list [--stopped] [(--uuid <uuid> |--name
<name>)]
List pools. If the --stopped option is used, list only
stopped pools. Otherwise, list only started pools. If a UUID or name is
specified, print more detailed information about the pool corresponding to
that UUID or name.
pool rename <old_pool_name> <new_pool_name>
Rename a pool.
pool destroy <pool_name>
Destroy a pool and all the filesystems created from
it.
pool add-data <pool_name> <blockdev>
[<blockdev>..]
Add one or more blockdevs to an existing pool, to enlarge
its storage capacity.
pool init-cache <pool_name> <blockdev>
[<blockdev>..]
Initialize a cache for an existing pool. Add one or more
blockdevs to a pool, to be used as cache instead of additional storage.
Typically, smaller and faster drives, such as SSDs, are used for this
purpose.
pool add-cache <pool_name> <blockdev>
[<blockdev>..]
Add one or more blockdevs to an existing pool with an
initialized cache.
pool extend-data <pool_name> [--device-uuid
<uuid>]
Increase the pool’s data capacity with additional
storage space offered by its component data devices through, e.g., expansion
of a component RAID device. Devices may be specified by their Stratis UUID. If
no devices are specified, then stratisd will attempt to make use of all data
devices belonging to the pool that appear to have been expanded.
pool bind <(nbde|tang)> <pool name> <url>
<(--thumbprint <thp> | --trust-url)>
Bind the devices in the specified pool to a supplementary
encryption mechanism that uses NBDE (Network-Bound Disc Encryption).
tang is an alias for nbde.
pool bind tpm2 <pool name>
Bind the devices in the specified pool to a supplementary
encryption mechanism that uses TPM 2.0 (Trusted Platform Module).
pool bind keyring <pool name> <keydesc>
Bind the devices in the specified pool to a supplementary
encryption mechanism using a key in the kernel keyring.
pool rebind clevis <pool name>
Rebind the devices in the specified pool using the Clevis
configuration with which the devices in the pool were previously bound.
pool rebind keyring <pool_name> <keydesc>
Rebind the devices in the specified pool using the
specified key description.
pool unbind <(clevis|keyring)> <pool name>
Unbind the devices in the specified pool from the
specified encryption mechanism.
pool set-fs-limit <pool name> <amount>
Set the limit on the number of file systems allowed
per-pool. This number may only be increased from its current value.
pool overprovision <pool name> <(yes|no)>
Set overprovisioning mode. If set to "yes", the
pool may allow overprovisioning, i.e, the sum of the logical sizes of the
Stratis filesystems supported by the pool may exceed the amount of data space
available.
pool explain <code>
Explain any code that might show up in the Alerts column
when listing a pool. Codes may be prefixed with an "I" for
"info", a "W" for "warning", or an "E"
for "error".
pool debug get-object-path <(--uuid <uuid> |--name
<name>)>
Look up the D-Bus object path for a pool given the UUID
or name.
filesystem create <pool_name> <fs_name>
[<fs_name>..] [--size <size>] [--size-limit
<size_limit>]
Create one or more filesystems from the specified pool.
If the --size option is specified, make each filesystem the specified
size. Otherwise, accept the stratisd default. if the --size-limit
option is specified, set the filesystem’s size limit on creation. If
the size limit is not set, the filesystem will be grown, as needed, up to the
maximum possible size. The filesystem size limit must be at least as large as
the filesystem size. NOTE: There is a temporary restriction on the number of
filesystems that can be specified with this command. Specifying more than one
filesystem will result in an error.
filesystem snapshot <pool_name> <fs_name>
<snapshot_name>
Snapshot the filesystem in the specified pool.
filesystem list [pool_name]
List all filesystems that exist in the specified pool, or
all pools, if no pool name is given.
filesystem destroy <pool_name> <fs_name>
[<fs_name>..]
Destroy one or more filesystems that exist in the
specified pool.
filesystem rename <pool_name> <fs_name>
<new_name>
Rename a filesystem.
filesystem set-size-limit <pool_name> <fs_name>
<size_limit>
Set the filesystem size limit. Must be at least as large
as the filesystem’s current size. To set the size limit to the same
value as the filesystem’s current size, use the keyword
"current".
filesystem unset-size-limit <pool_name> <fs_name>
Remove a filesystem size limit previously set.
filesystem debug get-object-path <(--uuid <uuid> |--name
<name>)>
Look up the D-Bus object path for a filesystem given the
UUID or name.
blockdev list [pool_name]
List all blockdevs that make up the specified pool, or
all pools, if no pool name is given.
blockdev debug get-object-path <(--uuid <uuid>)>
Look up the D-Bus object path for a blockdev given the
UUID.
key list
List all key-descriptions in the kernel keyring that can
be used for encryption.
key set <(--keyfile-path <path> | --capture-key)>
<key_desc>
Set a key in the kernel keyring for use with
encryption.
key reset <(--keyfile-path <path> | --capture-key)>
<key_desc>
Reset the key data of an existing key in the kernel
keyring.
key unset <key_desc>
Unset a key in the kernel keyring so it is no longer
available for encryption operations.
report <report_name>
Get a report from the daemon regarding its internal
state. The engine_state_report name will be supported in future releases. Any
other report name should be considered unstable and may be removed in a future
release. The JSON schema of any report must always be considered
unstable.
daemon version
Show the Stratis service’s version.
debug refresh
For all pools that are not stopped, rebuild their storage
stacks from the pool-level metadata stored on each pool’s devices. This
is not a standard administrative command; it is intended for trouble-shooting
and repair only.
OPTIONS¶
--key-desc
The key description of the key that should be used to
encrypt the created pool. The key description must correspond to a key set in
the kernel keyring with the key command.
--keyfile-path <path> | --capture-key
These mutually exclusive options allow a user to specify
a key used for encryption in one of two ways. The --keyfile-path option
requires an argument, the path to a file containing the key. If the
--capture-key option is selected instead, the user must enter the key
at the ensuing prompt. The key value is terminated at the first newline
character that the user enters, and does not include the newline character. On
the other hand, if the file specified as an argument for the
--keyfile-path option contains a newline character anywhere, the
newline character will be included in the key value.
--thumbprint <thp> | --trust-url
These mutually exclusive options allow a user to specify
that a tang server’s URL should be trusted and the server’s
credentials accepted without verification, or to supply a previously provided
thumbprint for verification.
--tang-url <url>
If creating a pool encrypted via NBDE using a tang
server, specifies the URL of the server.
--clevis <(nbde | tang | tpm2)>
The clevis method that should be used to encrypt the
created pool.
--no-overprovision
Do not allow the pool to allocate more logical space for
its filesystems than it has physical space available.
--size <size spec>
Used to specify the size of, e.g., a filesystem. The
specification format must follow the standard size specification format for
input (see below).
The format of a size specification is '<magnitude><unit specifier>'
where the magnitude must be a decimal integer and the unit specifier
may be any of 'B', 'KiB', 'MiB', 'GiB', 'TiB'. or 'PiB'.
ENVIRONMENT VARIABLES¶
STRATIS_DBUS_TIMEOUT
Sets a timeout for any Stratis D-Bus call. If this
environment variable is not set, a default value of 120 seconds is used for
the timeout. The accepted STRATIS_DBUS_TIMEOUT environment variable values
are:
1.an integer between 0 (inclusive) and 1073741823
(inclusive), which represents the timeout length in milliseconds
2.-1, which represents the libdbus default timeout
LIST OUTPUT FIELDS¶
FIELDS for stratis pool list
Name
The name of the pool.
Total / Used / Free
The physical usage statistics for the pool.
Properties
Boolean valued properties that the pool may have. Each
property has a two-letter camel-case code. If the pool does not have the
property, a ~, for negation, is prepended to the property code. If the
engine experienced an error when obtaining the property, a "?",
representing "unknown", is prepended to the property code. The
property codes are: Ca - indicates the pool has a cache, Cr - indicates the
pool is encrypted, Op - indicates the pool allows overprovisioning.
UUID
The UUID of the pool.
Alerts
Any unusual or urgent information about the pool of which
the user should be made aware.
FIELDS for stratis pool list --stopped
Name
The name of the pool.
UUID
The UUID of the pool.
# Devices
The number of devices used by the pool.
Key Description
The kernel key description used by the pool.
Clevis
The status of Clevis encryption ("present" or
"N/A").
FIELDS for stratis filesystem list
Pool
The name of the pool containing the filesystem.
Filesystem
The name of the filesystem.
Total / Used / Free
The size of the filesystem.
Created
The time the filesystem was created.
Device
The device path to use for mounting the filesystem.
UUID
The UUID of the filesystem.
FIELDS for stratis blockdev list
Pool Name
The name of the pool using the block device.
Device Node
The device node of the block device. A second device node
will be displayed in parentheses if the block device is encrypted. This device
node is the device node of the associated dm-crypt device.
Physical Size
The total size of the device on which stratisd places
Stratis metadata. If the device is encrypted, this size will be slightly
smaller than the total size of the device specified by the user; it will be
the size of the associated dm-crypt device. A second size will be displayed in
parentheses if stratisd has observed that the device has a size that is
different from the size that stratisd is making use of. This can happen if,
e.g., a RAID device was previously added to a pool and has since been
expanded.
Tier
The data tier type ("Data" or
"Cache")
UUID
The UUID of the block device.
FIELDS for stratis key list
Key Description
The key description corresponding to a key in the kernel
keyring that that can be used for encryption.
RESTRICTIONS¶
Encryption and a cache are mutually exclusive choices. If a pool
is encrypted, an attempt to initialize a cache will result in an error.
There is a restriction on the total size of the cache device of 32
TiB. Adding devices to the cache so that the cumulative size of all the
devices in the cache exceeds 32 TiB will result in an error.
NOTES¶
If a block device appears to be already in use, stratisd will
refuse to claim it. To allow use with stratisd, any signature on the device
must first be erased. Please carefully verify the identity and availability
of the device before taking such a step.
EXAMPLES¶
Example 1. Creating a Stratis pool
stratis pool create mypool /dev/sdb /dev/sdc
Example 2. Creating an encrypted pool
stratis key set --capture-key someKeyDescription
stratis pool create --key-desc someKeyDescription mypool /dev/sdb
/dev/sdc
Example 3. Creating a filesystem from a
pool
stratis filesystem create mypool data1
Example 4. Binding a pool’s devices to use
an NBDE policy for decryption
stratis pool bind nbde --trust-url mypool someTangServerUrl
REPORTING BUGS & DEVELOPMENT¶
GitHub for issues and development
Mailing list
stratis-devel@lists.fedorahosted.org for general
development discussion
Unknown values
If the stratisd D-Bus API returns values that stratis-cli
cannot interpret, stratis-cli will substitute "???". If encountered,
upgrading to the latest version of stratis-cli, or filing an issue, is
recommended.
Unobtainable values
If the stratisd D-Bus API indicates that a value is
unobtainable, stratis-cli will substitute "FAILURE". This may
indicate something wrong with the pool, blockdev, or filesystem. In some
cases, restarting stratisd may resolve the issue.
LICENSE¶
stratis-cli is licensed under the Apache License, Version
2.0. Software distributed under this license is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either expressed or implied.