salt.modules.bcache module

Module for managing BCache sets

BCache is a block-level caching mechanism similar to ZFS L2ARC/ZIL, dm-cache and fscache. It works by formatting one block device as a cache set, then adding backend devices (which need to be formatted as such) to the set and activating them.

It's available in Linux mainline kernel since 3.10

This module needs the bcache userspace tools to function.


Attach a backing devices to a cache set If no dev is given, all backing devices will be attached.

CLI example:

salt '*' bcache.attach sdc
salt '*' bcache.attach /dev/bcache1
Returns:bool or None if nuttin' happened
salt.modules.bcache.back_make(dev, cache_mode='writeback', force=False, attach=True, bucket_size=None)

Create a backing device for attachment to a set. Because the block size must be the same, a cache set already needs to exist.

CLI example:

salt '*' bcache.back_make sdc cache_mode=writeback attach=True
  • cache_mode -- writethrough, writeback, writearound or none.
  • force -- Overwrite existing bcaches
  • attach -- Immediately attach the backing device to the set
  • bucket_size -- Size of a bucket (see kernel doc)
salt.modules.bcache.cache_make(dev, reserved=None, force=False, block_size=None, bucket_size=None, attach=True)

Create BCache cache on a block device. If blkdiscard is available the entire device will be properly cleared in advance.

CLI example:

salt '*' bcache.cache_make sdb reserved=10% block_size=4096
  • reserved --

    if dev is a full device, create a partition table with this size empty.


    this increases the amount of reserved space available to SSD garbage collectors, potentially (vastly) increasing performance

  • block_size -- Block size of the cache; defaults to devices' logical block size
  • force -- Overwrite existing BCache sets
  • attach -- Attach all existing backend devices immediately
salt.modules.bcache.config(dev=None, **kwargs)

Show or update config of a bcache device.

If no device is given, operate on the cache set itself.

CLI example:

salt '*' bcache.config
salt '*' bcache.config bcache1
salt '*' bcache.config errors=panic journal_delay_ms=150
salt '*' bcache.config bcache1 cache_mode=writeback writeback_percent=15
Returns:config or True/False

Detach a backing device(s) from a cache set If no dev is given, all backing devices will be attached.

Detaching a backing device will flush it's write cache. This should leave the underlying device in a consistent state, but might take a while.

CLI example:

salt '*' bcache.detach sdc
salt '*' bcache.detach bcache1
salt.modules.bcache.device(dev, stats=False, config=False, internals=False, superblock=False)

Check the state of a single bcache device

CLI example:

salt '*' bcache.device bcache0
salt '*' bcache.device /dev/sdc stats=True
  • stats -- include statistics
  • settings -- include all settings
  • internals -- include all internals
  • superblock -- include superblock info

Trigger a start of the full bcache system through udev.

CLI example:

salt '*' bcache.start
salt.modules.bcache.status(stats=False, config=False, internals=False, superblock=False, alldevs=False)

Show the full status of the BCache system and optionally all it's involved devices

CLI example:

salt '*' bcache.status
salt '*' bcache.status stats=True
salt '*' bcache.status internals=True alldevs=True
  • stats -- include statistics
  • config -- include settings
  • internals -- include internals
  • superblock -- include superblock

Stop a bcache device If no device is given, all backing devices will be detached from the cache, which will subsequently be stopped.


'Stop' on an individual backing device means hard-stop; no attempt at flushing will be done and the bcache device will seemingly 'disappear' from the device lists

CLI example:

salt '*' bcache.stop

Read out BCache SuperBlock

CLI example:

salt '*' bcache.device bcache0
salt '*' bcache.device /dev/sdc

Return the bcache UUID of a block device. If no device is given, the Cache UUID is returned.

CLI example:

salt '*' bcache.uuid
salt '*' bcache.uuid /dev/sda
salt '*' bcache.uuid bcache0