Stratis 2.3.0 Release Notes

Stratis 2.3.0 adds additional flexibility to its encryption support via Clevis.

stratis 2.3.0

This release extends the pool unlock command, and adds two new commands, pool bind and pool unbind.

The pool bind command establishes an alternative mechanism for unlocking a pool. The user may select either the "tang" mechanism, which implements NBDE (Network-bound Disc Encryption) by means of a Tang server, or the "tpm2" mechanism, which uses TPM 2.0 (Trusted Platform Module) encryption. Binding the devices in a pool to a supplementary Clevis encryption policy does not remove the primary encryption mechanism, which uses a key in the kernel keyring.

The pool unbind command simply unbinds a previously added encryption policy from all the devices in the specified pool.

In the pool unlock command it is now necessary to specify the mechanism. Use clevis to make use of the Clevis unlocking policy previously specified for the devices in the pool. Use keyring, to make use of the mechanism that uses a key in the kernel keyring, which was introduced in Stratis 2.1.0. Note that the pool unlock command unlocks all currently locked pools.

stratisd 2.3.0

This release introduces two D-Bus interface revisions, which differ in the following way from the previous revisions.

org.storage.stratis2.Manager.r3 modifies the UnlockPool method to take an additional parameter, unlock_method, which may be keyring or clevis.

org.storage.stratis2.pool.r3 adds two new method: Bind and Unbind. The Bind method takes two arguments, pin and json. The pin argument designates the Clevis pin as a string, and the json argument encodes a Clevis configuration appropriate to the designated pin. The configuration is a JSON object. Besides Clevis information, it may include Stratis-specific keys that encode configuration decisions that Stratis may implement. At present there is just one such key: stratis:tang:trust_url. The Unbind method reverses a Bind action.

Remarks

The Bind method may be called with any Clevis pin and configuration; we expect that any valid Clevis pin and configuration can be used to bind the devices in a pool. However the Stratis project officially supports only the "tang" and "tpm2" pins as those are the pins that may be designated via stratis. Support for additional Clevis policies may be introduced into stratis in later releases.

When binding a supplementary encryption policy to the devices in a pool using Clevis, the primary key, which is the key in the kernel keyring which was originally used to encrypt each device, must be supplied. stratisd obtains the appropriate key from the kernel keyring in order to provide it to the Clevis binding mechanism. The correct key must be present in the keyring for the bind operation to succeed. It is not necessary for the user to specify the key, stratisd obtains the necessary information from the LUKS2 metadata on the devices in the pool.

In general, it is unwise to write a key consisting of arbitrary binary data to a keyfile. An accidental newline character in the data may cause the contents of the file to be truncated at the newline when read in one context while all the data may be read from the file in some other context.

We are not aware that such a mistake would result in any error in Stratis's operation when Stratis is used in the way that we recommend. We explicitly acknowledge that it might be possible, through some direct interaction with the stratisd D-Bus API, or by, e.g., setting a key in the kernel keyring without using stratis, to manufacture a situation where stratisd could not bind the devices in a pool, even when the correct key is set in the kernel keyring. We would not treat such a situation as evidence of a bug in Stratis.

Stratis 2.2.1 Release Notes

Stratis 2.2.1 is a bug fix release. It fixes the following bugs:

  • It was possible to cause stratisd to hang by leaving open a D-Bus connection when setting a key in the kernel keyring.
  • stratis would pass as arguments on the D-Bus and stratisd would accept relative, rather than absolute, path names to specify devices.
  • Pool and filesystem names that included characters that would be escaped by udev when constructing filesystem symlinks were permitted.
  • The man page entry for the key list command was missing.

Other general improvements were made, and several crate version requirements were increased.

Stratis 2.2.0 Release Notes

Stratis 2.2.0 now places Stratis filesystem symlinks in /dev/stratis, rather than /stratis. Stratis creates and maintains the symlinks by means of udev rules, rather than directly via stratisd as previously. The /stratis directory is neither created nor used by stratisd 2.2.0.

This release places management of the terminal setting for interactive encryption-key entry in stratisd rather than in stratis-cli.

This release also includes enhancements to the stratisd D-Bus interface, various bug fixes, and a change in the stratisd CLI specification for log levels.

stratisd 2.2.0

This release creates and maintains Stratis filesystem symlinks in /dev/stratis by means of udev rules. It includes a small Rust script, stratis_uuids_to_names which is invoked by the Stratis udev rule which sets the Stratis filesystem symlinks.

In the case where stratisd is updated in place, some filesystem symlinks may remain in /stratis. This release includes a shell script, stratis_migrate_symlinks.sh which may be used to clean up the /stratis directory and ensure that the correct symlinks exist in /dev/stratis. The script removes the /stratis directory once it has completed without error. The shell script relies on a small Rust script, stratis_dbusquery_version which is included with this version of stratisd.

This release also extends the D-Bus interface in a few ways:

  • It sends org.freedesktop.DBus.ObjectManager.InterfacesAddedand org.freedesktop.DBus.ObjectManager.InterfacesRemoved signals on the D-Bus whenever a D-Bus object is added to or removed from the D-Bus interface.
  • It adds a new D-Bus property, PhysicalPath, for the org.storage.stratis2.blockdev.r2 interface. This property is principally useful for encrypted Stratis block devices; it identifies the block device on which the Stratis LUKS2 metadata resides.
  • It adds a new key, LockedPools, to the org.storage.stratis2.FetchProperties.r2 interface for objects that implement the org.storage.stratis2.Manager interface. This key returns a D-Bus object that maps the UUIDs of locked pools to their corresponding key descriptions.

Please consult the D-Bus API Reference for the precise D-Bus specification.

Katacoda Tutorial

We would like to thank Red Hat for hosting a Katacoda tutorial for Stratis at lab.redhat.com/stratis. We hope that the tutorial will provide an easy and pleasant introduction to Stratis for new users.

Please note that the tutorial does not include the latest work on encryption, as it makes use of a prior version of Stratis, 2.0.0.

Stratis 2.1.0 Release Notes

Stratis 2.1.0 introduces support for encryption.

It supports per-pool encryption of the devices that form a pool's data tier. A pool may be encrypted, or its constituent encrypted devices may be activated, by means of a key stored in the kernel keyring.

stratisd 2.1.0

This release implements encryption support and adds several new D-Bus interfaces to administer or monitor that support.

It implements encryption support in the following way:

  • A single instance of stratisd can support both encrypted and unencrypted pools.
  • The choice to encrypt a pool must be made at the time a pool is created.
  • At present, the use of a cache and of encryption are mutually exclusive; if the pool is created with encryption enabled, then it is not possible to create a cache.
  • Each pool may be encrypted by means of a key in the kernel keyring; each encrypted pool may make use of a different key, but all devices in a pool are encrypted with a single key.
  • Any additional devices that are added to an encrypted pool's data tier will be encrypted using the key that was specified when the pool was initialized.

stratisd 2.1.0 supplies several new D-Bus interfaces:

  • org.storage.stratis2.manager.r1: This interface supplies an extended CreatePool method, to support an optional argument for encryption. In addition, it supplies a number of method for key management.
  • org.storage.stratis2.pool.r1: This interface supports explicit initialization of a cache tier. Previously, a cache was initialized as a side-effect of the addition of the first device to the cache tier. It also supports the new Encrypted property.
  • org.storage.stratis2.FetchProperties.r1: This interface supports an additional HasCache property.
  • org.storage.stratis2.Report.r1: This interface supports a set of ad-hoc reports about Stratis. The interface is unstable; the names by which the reports can be accesed are not guaranteed to remain stable, and the format of any report is only guaranteed to be valid JSON.

Please consult the D-Bus API Reference for the precise D-Bus specification.

The following are significant implementation details:

  • Each block device in an encrypted pool's data tier is encrypted with a distinct, randomly chosen MEK (Media Encryption Key) on initialization.
  • All devices belonging to a single encrypted pool share a single passphrase, supplied via the kernel keyring.
  • The release requires cryptsetup version 2.3.

We would like to thank our external contributor GuillaumeGomez for further work on metadata refactoring (stratisd issue 1573).

stratis-cli 2.1.0

This release requires stratisd 2.1.0. The user will observe the following changes:

  • The pool create command has been extended to allow encryption.
  • There is a new pool init_cache command, for initializing a cache.
  • There is a new subcommand, key, for key management tasks.
  • There is a new subcommand, report, which allows the display of certain reports generated by stratisd.
  • The output of pool list now includes a Properties column; each entry in the column is a string encoding the following properties of the pool:
    • whether or not it has a cache
    • whether or not it is encrypted

All commands now verify that stratis is communicating with a compatible version of stratisd and will fail with an appropriate error if stratisd is found to have an incompatible version.

Usage

To create an encrypted pool, a user must first ensure that a key is placed in the kernel keyring. We strongly encourage using the commands available via the stratis key subcommand for this task. This key, which is secret, has a corresponding key description, which is public.

An encrypted pool is then created by specifying the key description when using the pool create command.

It is necessary that the correct key and corresponding key description be set in the kernel keyring in order to set up a previously encrypted pool. Setting up a previously encrypted pool requires an explicit pool unlock command from the user. This command will attempt to unlock the devices belonging to any previously encrypted pool; it can only unlock all devices if a key for every encrypted pool is in the keyring. Once the devices belonging to a previously encrypted pool have been unlocked, the pool will be set up, and can be used in exactly the same manner as an unencrypted pool.

Cryptsetup Rust bindings release

Monday January 13, 2020

One major focus in the Stratis project recently has been adding an encryption layer for data in Stratis pools. Cryptsetup provides a library backend for programmatically setting up device encryption, so we decided to write Rust bindings to access the existing Cryptsetup functionality in Rust.

While designing the bindings, we took every opportunity to make use of Rust's type system, leveraging features like reference lifetimes and type parameters to ensure that as much of our public API as possible can be validated by the compiler.

Though these bindings were designed with Stratis in mind, it is intended to be general-purpose and so we encourage others to try it out. The license is MPLv2, but it becomes effectively GPL when linked with libcryptsetup. As a result, any project using our bindings will also need to be GPL or GPL-compatible.

If you're interested in seeing more, you can find the repository here.

Stratis 2.0.0 Release Notes

Wednesday November 6, 2019

Stratis 2.0 is a significant update for both the daemon and the CLI. The changes to the daemon are covered first, followed by the changes to the CLI.

stratisd 2.0.0

This release makes the D-Bus API more robust, reliable, predictable, and extensible. There are several significant changes:

  • The set of D-Bus properties has been reduced to a core set of fundamental and stable properties. Other filesystem, pool, or block devices properties are now obtainable via methods in the FetchProperties interface. This change increases the robustness of the D-Bus interface to failures occurring in any particular pool, filesystem, or block device, and decreases the computational cost of most operations requested by the Stratis CLI. Several properties, formerly returned as D-Bus properties, are now unavailable by means of the D-Bus. In every case, the reason for removing the property was that it did not represent a well-defined value. See project issue 52 for further details.

  • All D-Bus method calls are idempotent. This should make writing scripts using the D-Bus API much simpler and make reasoning about the behavior of the engine more straightforward. Henceforth, we will treat as a bug any non-idempotent behavior in the D-Bus API. See project issue 51 for further details.

  • All D-Bus size values are now returned in bytes. Again, this should make writing scripts against the D-Bus more straightforward, since it will be unnecessary for the script writer to change their interpretation of the number returned on the D-Bus depending on the value that it represents. See stratisd issue 1243 for further details.

Future enhancements to the D-Bus API will be implemented by means of additional versioned interfaces.

Please consult the D-Bus API Reference for the precise D-Bus specification.

stratis-cli 2.0.0

This release requires stratisd 2.0.0. The user will observe the following significant improvements:

  • The CLI is significantly more robust. Previously, there was a category of error conditions in pools, filesystems, and block devices that would make the CLI virtually unusable; this problem has now been entirely resolved. See project issue 52 for further details.

  • The CLI now reports errors consistently in conditions where a human user would generally expect an error to be reported. Previously, many commands in the CLI were idempotent, to facilitate scripting. Now there is a clear distinction between the CLI behavior and the stratisd D-Bus API behavior: the CLI behavior is designed strictly according to the expectations of a human user, the stratisd D-Bus API is the programmable interface. See project issue 51 for further details.

As always, anyone wishing to implement a program that uses Stratis for storage management is strongly advised to make use of the stratisd D-Bus API rather than the CLI.

stratis-cli 1.1.0 Release Notes

Wednesday October 2, 2019

With this release stratis now recognizes an environment variable, STRATIS_DBUS_TIMEOUT. This environment variable controls the timeout for any individual D-Bus call that stratis makes. You may want to set it to a higher value than the default, which is 120 seconds, if you are running tests or otherwise scripting via stratis, and wish to avoid erroneous errors resulting from slow operations in your testing environment. See stratis-cli issue 252 for further details.

This release also introduces simplified and more complete error-reporting. For stratis, it constitutes an error if any command issued results in a Python stack trace. If you experience any such incident, please report it in a GitHub issue, including the full stack trace, and circumstances that led up to the incident.

stratisd 1.0.6 Release Notes

Wednesday October 2, 2019

This release includes one significant bug fix and a substantial refactoring.

The bug was caused by an inconsistency in the metadata handling which led to a failure to properly update the Stratis metadata if stratisd was restarted in an environment where the system clock indicated a time earlier than when it had previously been running. See stratisd issue 1509 for further details.

Stratis 1.0 Release Notes

Friday September 28, 2018

New Features

Initial Stable Stratis Release

Stratis is a Linux local storage management tool that aims to enable easy use of advanced storage features such as thin provisioning, snapshots, and pool-based management and monitoring.

After two years of development, Stratis 1.0 has stabilized its on-disk metadata format and command-line interface, and is ready for more widespread testing and evaluation by potential users. Stratis is implemented as a daemon – stratisd – as well as a command-line configuration tool called stratis, and works with Linux kernel versions 4.14 and up.

Stratis 0.5 Release Notes

March 8, 2018

This release is suitable for developers and early testers. It should not be used with valuable data, and pools created with this release will not be supported in Stratis 1.0, due to upcoming on-disk format changes.