# salt.modules.btrfs

Module for managing BTRFS file systems.

salt.modules.btrfs.add(mountpoint, *devices, **kwargs)

  Add a devices to a BTRFS filesystem.

  General options:

  - nodiscard: Do not perform whole device TRIM

  - force: Force overwrite existing filesystem on the disk

  CLI Example:

      salt '*' btrfs.add /mountpoint /dev/sda1 /dev/sda2

salt.modules.btrfs.convert(device, permanent=False, keeplf=False)

  Convert ext2/3/4 to BTRFS. Device should be mounted.

  Filesystem can be converted temporarily so the further processing and rollback is possible, or permanently, where previous extended filesystem image gets deleted. Please note, permanent conversion takes a while as BTRFS filesystem needs to be properly rebalanced afterwards.

  General options:

  - permanent: Specify if the migration should be permanent (false by default)

  - keeplf: Keep `lost+found` of the partition (removed by default,

      but still in the image, if not permanent migration)

  CLI Example:

      salt '*' btrfs.convert /dev/sda1
      salt '*' btrfs.convert /dev/sda1 permanent=True

salt.modules.btrfs.defragment(path)

  Defragment mounted BTRFS filesystem. In order to defragment a filesystem, device should be properly mounted and writable.

  If passed a device name, then defragmented whole filesystem, mounted on in. If passed a moun tpoint of the filesystem, then only this mount point is defragmented.

  CLI Example:

      salt '*' btrfs.defragment /dev/sda1
      salt '*' btrfs.defragment /path/on/filesystem

salt.modules.btrfs.delete(mountpoint, *devices, **kwargs)

  Remove devices from a BTRFS filesystem.

  CLI Example:

      salt '*' btrfs.delete /mountpoint /dev/sda1 /dev/sda2

salt.modules.btrfs.devices()

  Get known BTRFS formatted devices on the system.

  CLI Example:

      salt '*' btrfs.devices

salt.modules.btrfs.features()

  List currently available BTRFS features.

  CLI Example:

      salt '*' btrfs.mkfs_features

salt.modules.btrfs.info(device)

  Get BTRFS filesystem information.

  CLI Example:

      salt '*' btrfs.info /dev/sda1

salt.modules.btrfs.mkfs(*devices, **kwargs)

  Create a file system on the specified device. By default wipes out with force.

  General options:

  - allocsize: Specify the BTRFS offset from the start of the device.

  - bytecount: Specify the size of the resultant filesystem.

  - nodesize: Node size.

  - leafsize: Specify the nodesize, the tree block size in which btrfs stores data.

  - noforce: Prevent force overwrite when an existing filesystem is detected on the device.

  - sectorsize: Specify the sectorsize, the minimum data block allocation unit.

  - nodiscard: Do not perform whole device TRIM operation by default.

  - uuid: Pass UUID or pass True to generate one.

  Options:

  - dto: (raid0|raid1|raid5|raid6|raid10|single|dup)

      Specify how the data must be spanned across the devices specified.

  - mto: (raid0|raid1|raid5|raid6|raid10|single|dup)

      Specify how metadata must be spanned across the devices specified.

  - fts: Features (call `salt <host> btrfs.features` for full list of available features)

  See the `mkfs.btrfs(8)` manpage for a more complete description of corresponding options description.

  CLI Example:

      salt '*' btrfs.mkfs /dev/sda1
      salt '*' btrfs.mkfs /dev/sda1 noforce=True

salt.modules.btrfs.properties(obj, type=None, set=None)

  List properties for given btrfs object. The object can be path of BTRFS device, mount point, or any directories/files inside the BTRFS filesystem.

  General options:

  - type: Possible types are s[ubvol], f[ilesystem], i[node] and d[evice].

  - force: Force overwrite existing filesystem on the disk

  - set: <key=value,key1=value1...> Options for a filesystem properties.

  CLI Example:

      salt '*' btrfs.properties /mountpoint
      salt '*' btrfs.properties /dev/sda1 type=subvol set='ro=false,label="My Storage"'

salt.modules.btrfs.resize(mountpoint, size)

  Resize filesystem.

  General options:

  - mountpoint: Specify the BTRFS mountpoint to resize.

  - size: ([+/-]<newsize>[kKmMgGtTpPeE]|max) Specify the new size of the target.

  CLI Example:

      salt '*' btrfs.resize /mountpoint size=+1g
      salt '*' btrfs.resize /dev/sda1 size=max

salt.modules.btrfs.subvolume_create(name, dest=None, qgroupids=None)

  Create subvolume name in dest.

  Return True if the subvolume is created, False is the subvolume is already there.

  name

    Name of the new subvolume

  dest

    If not given, the subvolume will be created in the current directory, if given will be in /dest/name

  qgroupids

    Add the newly created subcolume to a qgroup. This parameter is a list

  CLI Example:

      salt '*' btrfs.subvolume_create var
      salt '*' btrfs.subvolume_create var dest=/mnt
      salt '*' btrfs.subvolume_create var qgroupids='[200]'

salt.modules.btrfs.subvolume_delete(name=None, names=None, commit=None)

  Delete the subvolume(s) from the filesystem

  The user can remove one single subvolume (name) or multiple of then at the same time (names). One of the two parameters needs to specified.

  Please, refer to the documentation to understand the implication on the transactions, and when the subvolume is really deleted.

  Return True if the subvolume is deleted, False is the subvolume was already missing.

  name

    Name of the subvolume to remove

  names

    List of names of subvolumes to remove

  commit

    - 'after': Wait for transaction commit at the end

    - 'each': Wait for transaction commit after each delete

  CLI Example:

      salt '*' btrfs.subvolume_delete /var/volumes/tmp
      salt '*' btrfs.subvolume_delete /var/volumes/tmp commit=after

salt.modules.btrfs.subvolume_exists(path)

  Check if a subvolume is present in the filesystem.

  path

    Mount point for the subvolume (full path)

  CLI Example:

      salt '*' btrfs.subvolume_exists /mnt/var

salt.modules.btrfs.subvolume_find_new(name, last_gen)

  List the recently modified files in a subvolume

  name

    Name of the subvolume

  last_gen

    Last transid marker from where to compare

  CLI Example:

      salt '*' btrfs.subvolume_find_new /var/volumes/tmp 1024

salt.modules.btrfs.subvolume_get_default(path)

  Get the default subvolume of the filesystem path

  path

    Mount point for the subvolume

  CLI Example:

      salt '*' btrfs.subvolume_get_default /var/volumes/tmp

salt.modules.btrfs.subvolume_list(path, parent_id=False, absolute=False, ogeneration=False, generation=False, subvolumes=False, uuid=False, parent_uuid=False, sent_subvolume_uuid=False, snapshots=False, readonly=False, deleted=False, generation_cmp=None, ogeneration_cmp=None, sort=None)

  List the subvolumes present in the filesystem.

  path

    Mount point for the subvolume

  parent_id

    Print parent ID

  absolute

    Print all the subvolumes in the filesystem and distinguish between absolute and relative path with respect to the given <path>

  ogeneration

    Print the ogeneration of the subvolume

  generation

    Print the generation of the subvolume

  subvolumes

    Print only subvolumes below specified <path>

  uuid

    Print the UUID of the subvolume

  parent_uuid

    Print the parent uuid of subvolumes (and snapshots)

  sent_subvolume_uuid

    Print the UUID of the sent subvolume, where the subvolume is the result of a receive operation

  snapshots

    Only snapshot subvolumes in the filesystem will be listed

  readonly

    Only readonly subvolumes in the filesystem will be listed

  deleted

    Only deleted subvolumens that are ye not cleaned

  generation_cmp

    List subvolumes in the filesystem that its generation is >=, <= or = value. '+' means >= value, '-' means <= value, If there is neither '+' nor '-', it means = value

  ogeneration_cmp

    List subvolumes in the filesystem that its ogeneration is >=, <= or = value

  sort

    List subvolumes in order by specified items. Possible values: * rootid * gen * ogen * path You can add '+' or '-' in front of each items, '+' means ascending, '-' means descending. The default is ascending. You can combite it in a list.

  CLI Example:

      salt '*' btrfs.subvolume_list /var/volumes/tmp
      salt '*' btrfs.subvolume_list /var/volumes/tmp path=True
      salt '*' btrfs.subvolume_list /var/volumes/tmp sort='[-rootid]'

salt.modules.btrfs.subvolume_set_default(subvolid, path)

  Set the subvolume as default

  subvolid

    ID of the new default subvolume

  path

    Mount point for the filesystem

  CLI Example:

      salt '*' btrfs.subvolume_set_default 257 /var/volumes/tmp

salt.modules.btrfs.subvolume_show(path)

  Show information of a given subvolume

  path

    Mount point for the filesystem

  CLI Example:

      salt '*' btrfs.subvolume_show /var/volumes/tmp

salt.modules.btrfs.subvolume_snapshot(source, dest=None, name=None, read_only=False)

  Create a snapshot of a source subvolume

  source

    Source subvolume from where to create the snapshot

  dest

    If only dest is given, the subvolume will be named as the basename of the source

  name

    Name of the snapshot

  read_only

    Create a read only snapshot

  CLI Example:

      salt '*' btrfs.subvolume_snapshot /var/volumes/tmp dest=/.snapshots
      salt '*' btrfs.subvolume_snapshot /var/volumes/tmp name=backup

salt.modules.btrfs.subvolume_sync(path, subvolids=None, sleep=None)

  Wait until given subvolume are completely removed from the filesystem after deletion.

  path

    Mount point for the filesystem

  subvolids

    List of IDs of subvolumes to wait for

  sleep

    Sleep N seconds betwenn checks (default: 1)

  CLI Example:

      salt '*' btrfs.subvolume_sync /var/volumes/tmp
      salt '*' btrfs.subvolume_sync /var/volumes/tmp subvolids='[257]'

salt.modules.btrfs.usage(path)

  Show in which disk the chunks are allocated.

  CLI Example:

      salt '*' btrfs.usage /your/mountpoint

salt.modules.btrfs.version()

  Return BTRFS version.

  CLI Example:

      salt '*' btrfs.version