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 <redundancy|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.

COMMANDS

pool create [--redundancy <redundancy>] [--key-desc <key_desc>] <pool_name> <blockdev> [<blockdev>..]
    Create a pool from one or more block devices, with the given pool name.

pool list
    List all pools on the system.

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 unlock <(keyring | clevis)>
    Unlock all devices that are part of an encrypted pool registered with stratisd but that have not yet been opened. The available unlock methods are keyring or clevis.

pool bind <(nbde|tang)> <pool name> <key description> <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. The description of the key in the kernel keyring used to encrypt the devices must be supplied.

pool bind tpm2 <pool name> <key description>
    Bind the devices in the specified pool to a supplementary encryption mechanism that uses TPM 2.0 (Trusted Platform Module). The description of the key in the kernel keyring used to encrypt the devices must be supplied.

pool unbind <pool name>
    Unbind the devices in the specified pool from an existing supplementary encryption mechanism. Unbinding leaves the primary encryption mechanism, which uses a key in the kernel keyring, unaffected.

filesystem create <pool_name> <fs_name> [<fs_name>..]
    Create one or more filesystems from the specified pool. 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.

blockdev list [pool_name]
    List all blockdevs that make up the specified pool, or all pools, if no pool name is given.

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. This command is not supported as the report names and returned JSON schemas are unstable and may be changed at any time.

daemon redundancy
    List the redundancy levels that the Stratis service supports.

daemon version
    Show the Stratis service’s version.

OPTIONS

--redundancy
    The redundancy for the created pool. The only option is "none" which is also the default.

--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.

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 Physical
    The physical usage statistics for the pool (Total / Used / Free).

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.

FIELDS for stratis filesystem list

Pool Name
    The name of the pool containing the filesystem.

Used
    The amount of storage space used in the pool by this 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.

Physical Size
    The size of the device.

Tier
    The data tier type ("Data" or "Cache")

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 someKeyDescription someTangServerUrl

SEE ALSO

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

REPORTING BUGS & DEVELOPMENT

GitHub for issues and development
    https://github.com/stratis-storage, against either stratis-cli or stratisd projects, based on likelihood of issue being with the command-line tool or the service daemon.

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.