stratis(8)
==========

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] [--integrity <(no,pre-allocate)>] [--journal-size <journal_size>] [--tag-spec <tag_spec>] <pool_name> <blockdev> [<blockdev>..]::
     Create a pool from one or more block devices, with the given pool name.
     The --tag-spec and --journal-size options are used to configure the amount
     of space to reserve for integrity metadata.
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 [--keyfile-path KEYFILE_PATH | --capture-key] --unlock-method <(any | clevis | keyring)> <(--uuid <uuid> |--name <name>)>::
     Start a pool, specifying the pool by its UUID or by its name. Use the
     --unlock-method option to specify a method of unlocking the pool if it
     is encrypted. If an unlock method of any is specified the pool will be
     unlocked with any facility available that allows the pool to be unlocked.
     If --keyfile-path or --capture-key is specified, then the pool will use
     only the passphrase specified by either of these options; the pool will
     not be unlocked if the passphrase is incorrect. The --unlock-method
     option is required if --keyfile-path or --capture-key is used. If the
     value is any, the specified passphrase will be tried for all keyslots;
     otherwise the specified passphrase will be tried only for the keyslot
     corresponding to the specified method.
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.
pool debug get-metadata [--pretty] [--written] <(--uuid <uuid> |--name <name>)> ::
     Get the pool-level metadata for the specified pool. If '--written' is not
     set, get metadata that would be written if metadata were written now,
     otherwise get the most recently written metadata. If '--pretty' is set,
     format prettily, otherwise print all on one line.
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 schedule-revert <pool_name> <snapshot_name>::
     Set a flag so that when the pool is next started, the specified snapshot
     will overwrite its origin filesystem. A snapshot that is scheduled to
     overwrite its origin filesystem can not be destroyed; the scheduled
     revert must be cancelled before the snapshot or its origin can be
     destroyed.
filesystem cancel-revert <pool_name> <snapshot_name>::
     Cancel a scheduled revert.
filesystem debug get-object-path <(--uuid <uuid> |--name <name>)> ::
     Look up the D-Bus object path for a filesystem given the UUID or name.
filesystem debug get-metadata <pool_name> [--pretty] [--written] [--fs-name <fs-name>] ::
     Get the filesystem metadata for the specified pool and optionally
     specified filesystem. If '--written' is not set, get metadata that would
     be written if metadata were written now, otherwise get the most recently
     written metadata. If '--pretty' is set, format prettily, otherwise print
     all on one line.
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> [--no-sort-keys]::
        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. The keys in the JSON schema are sorted in the
        output, unless the --no-sort-keys option is set.
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).


SIZE SPECIFICATION FORMAT FOR INPUT
-----------------------------------
	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: Le - indicates that the pool is a legacy pool,
          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 pool list [(--uuid <uuid> |--name <name>)]

UUID::
	The UUID of the pool.

Name::
	The name of the pool.

Alerts::
	A list of all alerts on the pool, as a text summary.

Metadata Version::
	The metadata version that the pool is using.

Actions Allowed::
	What actions may be taken on the pool. Generally the pool will be
	listed as fully operational.

Cache::
	Whether or not the pool has a cache.

Filesystem Limit::
	The maximum number of filesystems the pool allows.

Allows Overprovisioning::
	Whether or not the pool allows overprovisioning.

Encryption Enabled:
	Whether or not encryption is enabled for this pool.

Encryption Enabled: Key Description::
	The key description, if the pool is encrypted using a key in the
	kernel keyring. Only displayed if encryption is enabled.

Encryption Enabled: Clevis Configuration::
	The Clevis configuration, if the pool is encrypted via Clevis. Only
        displayed if encryption is enabled.

Space Usage: Fully Allocated::
	Whether or not all the space on a pool's devices has been allocated
	for some purpose.

Space Usage: Size::
	The total size of all the devices in the pool.

Space Usage: Allocated::
	The space on the devices allocated for some purpose, e.g., to store
	Stratis filesystem metadata or user data. Once space has been allocated
	for one purpose, it can not, in general, be reclaimed and used for
        another purpose.

Space Usage: Used::
	The space on the devices that is in use. Used space can be reclaimed.
	For example, destroying a Stratis filesystem will reduce this value.

FIELDS for stratis pool list [(--uuid <uuid> |--name <name>)] --stopped

UUID::
	The UUID of the pool.

Name::
	The name of the pool.

Metadata Version::
	The metadata version that the pool is using.

Encryption Enabled::
	Whether or not encryption is enabled.

Encryption Enabled: Key Description::
	The key description, if the pool is encrypted using a key in the
	kernel keyring. Only displayed if metadata version is 1 and encryption
        is enabled.

Encryption Enabled: Clevis Configuration::
	The Clevis configuration, if the pool is encrypted via Clevis. Only
        displayed if metadata version is 1 and encryption is enabled.


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 filesystem list [(--uuid <uuid> |--name <name>)]

UUID::
	The UUID of the filesystem.

Name::
	The name of the filesystem.

Pool::
	The name of the filesystem's pool.

Device::
	The device path to use for mounting the filesystem.

Created::
	The time the filesystem was created.

Snapshot origin::
	If this filesystem is a snapshot, its origin. If the filesystem is
	a snapshot, whether or not it is scheduled to replace its origin
	next time the pool is started.

Sizes::
	The logical size of the Stratis filesystem, the total space actually
	used, and the logical amount free on the Stratis filesystem. Since
	every Stratis filesystem holds an XFS filesystem, a new Stratis
	filesystem will have a non-zero amount used for the XFS filesystem
	metadata.


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
--------
.Creating a Stratis pool
====
stratis pool create mypool /dev/sdb /dev/sdc
====
.Creating an encrypted pool
====
stratis key set --capture-key someKeyDescription

stratis pool create --key-desc someKeyDescription mypool /dev/sdb /dev/sdc
====
.Creating a filesystem from a pool
====
stratis filesystem create mypool data1
====
.Binding a pool's devices to use an NBDE policy for decryption
====
stratis pool bind nbde --trust-url mypool someTangServerUrl
====

SEE ALSO
--------
*mount*(8), *umount*(8), *fstab*(5)

REPORTING BUGS & DEVELOPMENT
-----------------------------
GitHub for issues and development::
        https://github.com/stratis-storage/project/issues
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.
