Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


encrypted_blockdevice (1) Versions 0.1.0

A cookbook and LWRPs to manage block device encryption, offering many options for different scenarios.

cookbook 'encrypted_blockdevice', '~> 0.1.0', :supermarket
cookbook 'encrypted_blockdevice', '~> 0.1.0'
knife supermarket install encrypted_blockdevice
knife supermarket download encrypted_blockdevice
Quality 17%


This cookbook contains an LWRP to manage individual encrypted block devices using the cryptsetup package.

Additionaly it contains a LWRP to create one or more encrypted block devices according to override attributes instead of recipe contents.

There are two types of storage possible: device storage and file storage.

Both types of storage get mapped back to the name of the encrypted block device given.

When this cookbook is run by a recipe, the default behaviour is to attempt to create the encrypted block devices from the encrypted_blockdevices key/attributes. See the Usage section and example recipe for how to use this key, and a few options on the attributes.

There are four kinds of keystore available, giving differing levels of security and bootability:

  • discard Provides a one-time use block device with a randomly-generated key kept in RAM. Data will not be recoverable after reboot or cryptdisks shutdown/restart.

  • vault Stores the key for the block device in a vault-encrypted databag on the chef server. When the cookbook/chef runs after reboot, the block device will be decrypted and mounted.

  • databag Stores the key for the block device in a normal databag on the chef server. When the cookbook/chef runs after reboot, the block device will be decrypted and mounted.

  • local Stores a local (on the filesystem - such as /etc/secrets/device.key) randomly-generated key file. This will be mounted by the system using the crypttab on reboot.

These modes are ordered from most secure (and hard to recover) to least secure (and easily recoverable).

Keystore Caveats

  • In discard mode you must be absolutely sure you can lose the local copy of the data - backups are absolutely critical in this mode.

  • In vault and databag mode we will use the Chef API as a keystore - this means the data should be recoverable once chef has run after a reboot, unless the key is delete from the chef server.

You should create the "encrypted_blockdevice_keystore" databag so that items can be put into it by this cookbook. This databag's name is set in the cookbook attributes and can be changed, but the items are named according to a pattern based upon the node name and device. Your node names must always be uniquely generated to avoid collisions/key sharing !

  • In local mode, the key is kept in a file on the local filesystem, if the key is available after reboot, the data should be recoverable without intervention before chef runs.

Conventional wisdom and Cryptographic common sense is that you should not keep the keys for secrets next to the secrets they protect, consequently a local keystore with keyfile is not recommended when your secrets are dangerous if compromised.

Other Caveats

The author of this cookbook believes cookbooks should not overlap in behaviour or ability. Each cookbook should do one thing and do it well.

Consequently this cookbook explicitely does not create filesystems themselves - all it does is encrypt underlying blocks and present them at an unencrypted location for use - you should use the filesystem cookbook to make use of the unencrypted location.

We include some examples that combine this cookbook with the filesystem cookbook below.



  • Ubuntu 12.04 (original dev target in 2013)
  • Ubuntu 14.04 (dev target in 2016)
  • Probably other recent distros with the same tools (rhel releases have been partly tested).


  • The cryptsetup package, by one name or another.
  • Openssl for key generation.

Special Chef Permissions (to get past the 403 permission denied on databag upload)

  • knife acl add group clients containers data create,update,delete
  • knife acl add client 'hostname1,hostname2' container clients read
  • knife group add client 'hostname1,hostname2' admins

We do not call the package manager directly, but use the chef 'package' abstraction. Attributes are provided to manage the package and service name if they differ.

Main Attributes


Hash of encrypted_blockdevices to setup.

node[:encrypted_blockdevices] keys:

Each encrypted block device's key is the label: This explains each key in a filesystems entry. The label should probably not exceed 12 characters.

We also let you use your own top-level key if you want - see the default recipe and example recipes.

Cookbook Attributes:

node[:encrypted_blockdevice][:keystore_databag_name] = "encrypted_blockdevice_keystore"

The name of the encrypted blockdevice keystore to use, if the keystore is of the databag type.

node[:encrypted_blockdevice][:cryptsetup_package] = "cryptsetup"
node[:encrypted_blockdevice][:cryptdisks_service] = "cryptdisks"

The following attributes are good for debian and ubuntu - they are provided for extension to other distros.

Backing Location Options


Path to the device to create the filesystem upon.


Path to the file-backed storage to be used for a loopback device. If the file is not present it will be created, a size is needed if you want to have a device larger than 100 Megabytes.

Keystore Options

keystore discard|vault|databag|local

Key store to use for creating the filesystem's key.

admins johnny,sarah

Chef admins of the vault keystore - only to be used with the vault keystore.. not databag.

keyfile /path/to/secret

File location to use for creating the filesystem's key in local keystore mode.

Encryption Options

keylength the encryption key's length (default: 1024)

Used when the key is generated.

cipher the cipher to use. (default "aes-cbc-essiv:sha256")

Used when the filesystem is encrypted for us.

File Backing Options

size 10000

The size in Megabytes, only used for file Backed storage.

sparse Boolean (default: true)

Sparse file creation, used by the file storage, by default we use this for speed, but you may not want that. Set to false in that case.

Other Options

cryptsetup_args cryptsetup arguments to use. (default "create") - when not "create" we reverse the device/name order given to the cryptsetup command.

Can be used to specify additional or different arguments. Recent versions of cryptsetup this should be changed to "open -type type" where type is luks, plain, loopaes and tcrypt. See the cryptsetup man page.



This recipe will install the package, start the service and make available in encrypted form any block devices found at the expected key (encrypted_blockdevices)


This represents an example of creating a few small encrypted filesystems, or using the create_all_from_key LWRP on a different key information.

Usage: Direct Resource/Provider

include_recipe "encrypted_blockdevice"

encrypted_blockdevice "cryptfs" do
  size 1000
  file "/mnt/cryptfs.file"
  keystore "local"
  keyfile "/etc/secrets/cryptfs.key"
  action :create

include_recipe "filesystem"

filesystem "cryptfs" do
  fstype "ext4"
  mount "/mnt/cryptfs"
  noenable true

Usage: Attribute Key

Runlist: encrypted_blockdevice

  "encrypted_blockdevices": {
    "raidcrypt": {
      "device": "/dev/md0",
      "keystore": "vault",
      "admins" : "alex"
    "local": {
      "file": "/local.file",
      "keystore": "local",
      "keyfile": "/etc/secrets/local.key",
      "size": 10000
    "supersecret": {
      "file": "/mnt/notsparse.file",
      "sparse": false,
      "keystore": "discard",
      "size": 1000

Getting a usable filesystem

If you want filesystems, use the filesystem cookbook with the filesystems key:

Runlist: encrypted_blockdevice, filesystem

  "encrypted_blockdevices": {
    "raidcrypt": {
      "device": "/dev/md0",
      "keystore": "vault",
      "admins" : "alex"
  "filesystems": {
    "raidcrypt": {
      "device": "/dev/mapper/raidcrypt",
      "fstype": "xfs",
      "mount": "/mnt"


License and Authors

Author - Databag and Vault pieces and current mainainer:
Alex Trull (@AlexanderTrull) partly on behalf of Medidata Solutions.
Original Author/Sponsor: Neil Schelly (@neilschelly)
Copyright 2013, Dyn, Inc (@DynInc)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,

See the License for the specific language governing permissions and
limitations under the License.

Dependent cookbooks

chef-vault >= 0.0.0

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

Collaborator Number Metric

0.1.0 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric

0.1.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Foodcritic Metric

0.1.0 failed this metric

FC007: Ensure recipe dependencies are reflected in cookbook metadata: encrypted_blockdevice/recipes/example.rb:59
FC064: Ensure issues_url is set in metadata: encrypted_blockdevice/metadata.rb:1
FC065: Ensure source_url is set in metadata: encrypted_blockdevice/metadata.rb:1
FC066: Ensure chef_version is set in metadata: encrypted_blockdevice/metadata.rb:1
FC069: Ensure standardized license defined in metadata: encrypted_blockdevice/metadata.rb:1
FC072: Metadata should not contain "attribute" keyword: encrypted_blockdevice/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: encrypted_blockdevice/resources/create_all_from_key.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: encrypted_blockdevice/providers/create_all_from_key.rb:53
FC085: Resource using new_resource.updated_by_last_action to converge resource: encrypted_blockdevice/providers/default.rb:33
FC085: Resource using new_resource.updated_by_last_action to converge resource: encrypted_blockdevice/providers/default.rb:43
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

No Binaries Metric

0.1.0 passed this metric

Testing File Metric

0.1.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must contain a file

Version Tag Metric

0.1.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of, and your repo must include a tag that matches this cookbook version number