BARREL(8)

📦 version 0.2.8, in opensuse-leap 16.0

✨ NAME ✨

barrel — command-line program for storage management. That’s the whole vibe, bestie: section 8’s storage-management main character. 💅

🌸 SYNOPSIS 🌸

barrel [--global-opts] command [--command-opts] [block-devices]

barrel [--global-opts]

💖 DESCRIPTION 💖

Okay so barrel is the command-line program for storage management, and it’s lowkey a multi-tool for file systems, LUKS, RAIDs and LVM. The main feature? It combines the various tools you’d need to manage all those different storage systems into one tool. Like — with a single barrel command, you can create partitions on several disks, create a RAID from those partitions, and create a file system on the RAID. Iconic. ✨

barrel probes the complete storage system at startup and does not save the state between invocations. That means you can mix barrel with other storage tools — although, fr fr, not concurrently in general. 🫶

🦋 CONCEPTS 🦋

🎀 Script and Interactive Mode 🎀

barrel can run in either script or interactive mode. In script mode the command must be provided on the command line. If no command is provided on the command line, interactive mode starts and a prompt asks for the commands. Cute, right? 💖

🌈 Pool 🌈

Pools are a set of devices and let barrel find suitable disk space on its own. For example, when the system has several SSDs and the user wants to create a file system on some SSD, barrel can pick an SSD with enough space automatically. Slay. So far, devices in a pool must have a partition table to be usable. No table, no entry, iykyk. 🎀

🧚 Stack 🧚

barrel has a stack that allows commands to be chained. For example, creating a RAID places the resulting RAID on the stack. A consecutive command to create a file system can then pick the RAID from the stack. Using the stack means the user does not have to deal with the name of the newly created RAID, and thus the two commands can be provided on the command line. Obsessed. 💅

The stack can hold different objects: storage objects (e.g. block devices, LVM volume groups or file systems), a mark, and arrays. Arrays are constructed using the [ and ] commands. 🦋

⭐ Devicegraph ⭐

barrel saves all information about storage devices and file systems, together with their relations, in a devicegraph. At startup the system is probed and the state is saved in the probed and the staging devicegraphs. All commands, except the commit command, only modify the staging devicegraph. Main character energy for staging, honestly.

barrel makes a backup of the staging devicegraph whenever it is modified. The last backup can be restored with the command undo. 💖

During commit, barrel runs actions to make the system match the staging devicegraph. In script mode a commit is done automatically if needed. No cap.

💀 Modi Operandi of Commands 💀

Many commands operate significantly differently based on the provided options. It’s giving “same command, different era.”

For example, when creating a file system using create xfs /dev/sdb1, the XFS is created on the partition /dev/sdb1. On the other hand, the command create xfs /dev/sdb --size 10G will create a 10 GiB partition on /dev/sdb and the XFS on the new partition. And the command create xfs will take a device from the stack and create the XFS on that device. Periodt. 🔥

👑 GLOBAL OPTIONS 👑

  • -q, --quiet — suppress normal output. Error messages will still be printed, though. 🫶
  • -v, --verbose — increase verbosity. Tell me more, bestie. ✨
  • -t, --table-style style — specifies table style. Table style is identified by an integer number. 🎀
  • --color — use colors in output. 🌈
  • --no-color — do not use colors in output. 🙈
  • --dry-run — do not commit anything to disk. The ultimate “look, don’t touch.” 💅
  • --rootprefix path — prepend various path (mount points and files in /etc) with a rootprefix. Useful when running in an installation or rescue system. 🧚
  • -a, --activate — activate storage systems at startup. Useful when running in an installation or rescue system. ⭐
  • --yes — do not prompt for confirmation but assume the answer yes. Use with extreme caution. 💀 Dramatic but true.
  • -h, --help format — print help and exit. 🦋
  • --version — print version and exit. 👑

💅 COMMANDS 💅

barrel provides a number of commands. Many commands have specific options, which are listed in this section. These command-specific options must be specified after the name of the command. For several commands some options are mandatory. So yes, order matters, bestie. 🎀

[

Starts an array construction by pushing a mark on the stack. 🎀

]

Ends an array construction by creating a new array from the objects on the stack upto the next mark, removing the objects and the mark from the stack, and finally pushing the new array onto the stack. 🦋

clear

Clears the stack. 🧹

commit

Commits changes to disk and quits. 💾

create encryption [device]

Creates a new encryption device. 🔐

  • -t, --type type — set encryption type. Possible values are luks1 and luks2.
  • -n, --name name — name of device-mapper device.
  • --label label — label of device-mapper device. Only for LUKS2.
  • --activate-by type — set the activate-by type used in /etc/crypttab. Possible values are device, path, id, uuid and label (only for LUKS2). The default is usually uuid. If the selected type is not available the fallback is device.
  • --activate-options options — options in /etc/crypttab for the encryption.
  • --pool-name name — name of pool from which to take underlying device.
  • -s, --size size — approximate size of resulting encryption device.
  • --key-file — set a key file. The key file is used during commit and in /etc/crypttab. Also the key file must already exist.
  • --key-size — set the key size in bits. Must be at least a multiple of 8. See cryptsetup for more details.
  • --cipher — set the cipher. See cryptsetup for more details.
  • --pbkdf — set the PBKDF (Password-Based Key Derivation Function). See cryptsetup for more details.
  • --no-crypttab — do not add the encryption in /etc/crypttab.
  • --force — force creation if block device is in use.

Possible Modi Operandi are:

  • Pool — the encryption device is created on a new partition on a block device from the pool. The options --pool-name and --size are required.
  • Block Device — the encryption device is created directly on the provided block device. The option --size is not allowed.
  • Partitionable — the encryption device is created on a new partition on the provided block device, which must be partitionable. The option --size is required.
  • Block Device from Stack — the encryption device is created directly on the block device from the stack. The option --size is not allowed.
  • Partitionable from Stack — the encryption device is created on a new partition on the block device from the stack, which must be partitionable. The option --size is required.

create filesystem [device]

Creates a new file system. 🌸

  • -t, --type type — set file system type. Possible values are bcachefs, btrfs, exfat, ext2, ext3, ext4, f2fs, jfs, nilfs2, ntfs, reiserfs, swap, udf, vfat, xfs.

Not all file systems may be available on the system.

  • -l, --label label — set label of file system.
  • -p, --path path — path to mount the file system.

For swap the path may be 'swap' or 'none'.

  • --mount-by type — set the mount-by type used in /etc/fstab. Possible values are device, path, id, uuid and label. The default is usually uuid. For some devices it is different, e.g. for LVM logical volumes it is device since LVM has stable device names. If the selected type is not available the fallback is device.
  • --mount-options options — mount options for the file system.
  • --mkfs-options options — options for mkfs command. The options are injected as-is to the command so must be properly quoted.
  • --tune-options options — options for the file system tune command. The options are injected as-is to the command so must be properly quoted. Only supported for ext2, ext3 and ext4.
  • --pool-name options — name of pool from which to take underlying device.
  • -s, --size size — approximate size of the block device or sum of the sizes of the block devices for the file system.

Due to file system metadata and for btrfs also data duplication the usable space of the resulting file system can be much smaller.

  • -d, --devices number — for btrfs the number of underlying devices for the file system. Default is 1. The special value of 'max' uses all devices provided or all devices of the pool.
  • --profile profile — btrfs profiles for data and metadata. Either one profile can be provided for both data and metadata, or two profiles separated by comma, the first for data and the second for metadata.
  • --no-fstab — do not add the file system in /etc/fstab.
  • --force — force creation if block device is in use.

Possible Modi Operandi are:

  • Pool — the file system is created on a new partition on a block device from the pool. The options --pool-name and --size are required.
  • Block Device — the file system is created directly on the provided block device. The option --size is not allowed.
  • Partitionable — the file system is created on a new partition on the provided block device, which must be partitionable. The option --size is required.
  • Block Devices from Stack — the file system is created directly on block devices from the stack. The option --size is not allowed. The top object on the stack must be a block device or an array of block devices.
  • Partitionables from Stack — the file system is created on new partitions on the block devices from the stack. The option --size is required. The top object on the stack must be a partitionable block device or an array of partitionable block devices.

create lv

Creates a new LVM logical volume. 💜

  • -v, --vg-name vg-name — name of volume group to use.
  • -n, --name name — name of new logical volume.
  • -s, --size size — approximate size of resulting logical volume.
  • --stripes stripes — number of stripes for the logical volume. Default is 1. The special value of 'max' uses all underlying devices of the volume group.
  • --stripe-size stripe-size — the stripe size. yeah. that's her 💅

Possible Modi Operandi are:

  • Volume Group — the logical volume gets created on the volume group you hand over. --vg-name is required here, no cap.
  • Volume Group from Stack — the logical volume gets created on the volume group that's chilling on top of the stack 🥞

create partition-table [device]

Brand new partition table, fresh start, clean slate energy ✨

  • -t, --type type — set the partition table type. The possible values are gpt and ms-dos.
  • --force — force the creation even when the block device is in use. spicy 🌶️

Possible Modi Operandi are:

  • Partitionable — the partition table is built on the block device you provided, and that device must be partitionable.
  • Partitionable from Stack — the partition table is built on the block device from the stack, which must be partitionable.

create pool [devices]

Creates a shiny new pool stuffed with devices 🫶

  • -n, --name name — the name of the pool.

create raid [devices]

Creates a RAID. iconic, honestly 🔥

  • -l, --level level — set the RAID level. Possible values are linear, 0, stripe, 1, mirror, 4, 5, 6 and 10.
  • -n, --name name — set the name of the RAID.
  • --pool-name name — name of the pool to grab the underlying devices from.
  • -s, --size size — approximate size of the resulting RAID.
  • --metadata metadata — the RAID metadata version. Possible values are 1.0, 1.1 and 1.2, although other values might work too. If you don't pass the option, mdadm's default gets used (which is 1.2 at present).
  • -d, --devices number — number of RAID and spare devices. Possible formats are:
    • r — create a RAID with r RAID devices and zero spare devices.
    • r+s — create a RAID with r RAID devices and s spare devices.
    • +s — create a RAID with n−*s* RAID devices and s spare devices.

The default is to use n. And n is the number of devices provided, or the devices of the pool.

  • --chunk-size chunk-size — the chunk size.
  • --force — force creation even if the block devices are in use.

Possible Modi Operandi are:

  • Pool — the RAID is created on new partitions on block devices from the pool. --pool-name and --size are required.
  • Block Devices — the RAID is created directly on the block devices you provided. --size is not allowed here 🙅‍♀️
  • Partitionables — the RAID is created on new partitions on the block devices you provided, which must be partitionable. --size is required.

create vg [devices]

Creates a new LVM volume group. big girl moves 👑

  • -n, --name name — name of the new volume group.
  • --pool-name name — name of the pool to take the underlying devices from.
  • -s, --size size — approximate size of the resulting volume group.
  • -d, --devices number — number of underlying devices for the volume group. Default is 1. The special value 'max' uses all devices provided, or all devices of the pool.
  • --extent-size extent-size — the extent size.
  • --force — force creation even if the block devices are in use.

Possible Modi Operandi are:

  • Pool — the volume group is created on new partitions on block devices from the pool. --pool-name and --size are required.
  • Block Devices — the volume group is created directly on the block devices you provided. --size is not allowed.
  • Partitionables — the volume group is created on new partitions on the block devices you provided, which must be partitionable. --size is required.
  • Block Devices from Stack — the volume group is created directly on the block devices from the stack. --size is not allowed. The top object on the stack must be a block device or an array of block devices.
  • Partitionables from Stack — the volume group is created on new partitions on the block devices from the stack. --size is required. The top object on the stack must be a partitionable block device or an array of partitionable block devices.

dup

Duplicates the top object of the stack. copy-paste but make it filesystem 💅

exch

Exchanges the two top objects of the stack. swap era 🌸

extend pool devices

Adds devices to a pool.

  • -n, --name name — name of the pool.

help [main-command [sub-command]]

Shows help. she's helpful like that 🫶

load devicegraph

Loads the staging devicegraph from a file.

okay so this function is still in development — use with great care, bestie 😭
  • -n, --name name — name of the devicegraph file.
  • -m, --mapping name — name of the mapping file.

load pools

Explicitly loads pools from /etc/barrel/pools.json. Lowkey you don't have to, because pools are automatically loaded at startup. convenient ✨

pop

Removes the top object from the stack. bye bestie 👋

quit

Quits barrel. dramatic exit encouraged 🎀

reduce pool devices

Removes devices from a pool.

  • -n, --name name — name of the pool.

remove device devices

Removes a device and all the devices and file systems using it. scorched earth, but make it storage 🔥

When you remove a RAID or encryption device, the underlying partitions are also removed. This isn't possible if it would cause used partitions to be renumbered — like logical partitions on an MS-DOS partition table, for example.

  • --keep-partitions — keep the underlying partitions.

remove pool devices

Removes a pool.

  • -n, --name name — name of the pool.

rename pool

Renames a pool. glow-up for a pool 🦋

  • -o, --old-name name — old name of the pool.
  • -n, --new-name name — new name of the pool.

save devicegraph

Saves the devicegraph to a file.

  • -n, --name name — name of the devicegraph file.
  • --probed — save the probed devicegraph instead of the staging one.

save pools

Explicitly saves pools in /etc/barrel/pools.json. Heads up: pools are also saved during commit if they were modified, so this is the manual override vibe.

show commit

Shows commit actions.

show dasds

Shows DASDs.

  • --probed — show the DASDs of the probed devicegraph instead of the staging one.
  • --no-partitions — don't show partitions on the DASDs.

show disks

Shows disks.

  • --probed — show the disks of the probed devicegraph instead of the staging one.
  • --no-partitions — don't show partitions on the disks.

show encryptions

Shows encryption devices.

  • --probed — show the encryption devices of the probed devicegraph instead of the staging one.

show filesystems

Shows file systems.

  • --probed — show the file systems of the probed devicegraph instead of the staging one.

show multipaths

Shows multipath devices.

  • --probed — show the multipath devices of the probed devicegraph instead of the staging one.
  • --no-partitions — don't show partitions on the multipath devices.

show pools

Shows pools.

  • --probed — use the probed devicegraph instead of the staging one to find the devices of the pools.

Devices that aren't currently usable — because they don't have a partition table — get marked with an '!'. so watch for that 🚩

show raids

Shows RAIDs.

  • --probed — show the RAIDs of the probed devicegraph instead of the staging one.
  • --no-partitions — don't show partitions on the RAIDs.

show tree devices

Shows a tree of block devices for the devices you provide. cute little family tree 🌳

  • --up — show the tree moving up from the devices.
  • --down — show the tree moving down from the devices.
  • --probed — show the tree of the probed devicegraph instead of the staging one.

show vgs

Shows LVM volume groups.

  • --probed — show the volume groups of the probed devicegraph instead of the staging one.

stack

Prints the stack. peek at what's on top 🥞

undo

Restores the staging devicegraph to the last backup. ctrl+z but make it enterprise 💀

✨ EXAMPLES ✨

Real ones, ready to copy. go off bestie 💖

barrel create xfs /dev/sdb1 --path /test

Create an XFS on /dev/sdb1 and mount it at /test.

barrel create xfs /dev/sdb --size 10G --path /test

Create a 10 GiB partition on /dev/sdb with an XFS, and mount it at /test.

barrel create btrfs --size 1TiB --pool "SSDs (512 B)" --devices 2 --profiles raid0,raid1 --path /test

Create two 0.5 TiB partitions on two devices from the pool "SSDs (512 B)", create a btrfs with the raid0 profile for data and the raid1 profile for metadata on those partitions, and mount it at /test.

barrel create raid1 /dev/sd[bc]1 xfs --path /test

Create a RAID1 on /dev/sdb1 and /dev/sdc1 with an XFS, mounted at /test.

barrel create raid5 --size 1TiB --pool "HDDs (512 B)" --devices 3+1 xfs --path /test

Create a 1 TiB RAID5 with 3 devices and 1 spare from devices in the pool "HDDs (512 B)", plus an XFS on the RAID mounted at /test.

barrel create vg --name vg1 --size 1TiB /dev/sdb lv --name lv1 --size 100G xfs --path /test

Create a new 1 TiB partition on /dev/sdb, create a volume group named vg1 using that partition, create a logical volume named lv1 with size 100G inside the volume group, and finally create an XFS on the logical volume and mount it at /test. the full pipeline, she ate 🍓

🎀 FILES 🎀

  • /etc/barrel/pools.json — the JSON file defining pools.
  • /var/log/barrel.log — the logfile. Please include this file in bug reports — it's literally the receipts 🙏

💀 BUGS AND MISSING FEATURES 💀

not gonna lie, there's some stuff still cooking:

  • Validation of input is unfinished.
  • Missing tools are not installed on demand.
  • Tools doing automounts — e.g. systemd and desktop environments — can cause race conditions. chaos, honestly.
  • Incomplete support for multipath, BIOS RAIDS and DASDs.
  • Tab completion in the interactive mode is not context aware.

🌈 HOMEPAGE 🌈

http://github.com/openSUSE/barrel/

👑 AUTHORS 👑

Arvin Schnell <aschnell@suse.com>

🌸 SEE ALSO 🌸

parted(8), mkfs(8), mount(8), mdadm(8), lvm(8), cryptsetup(8), fstab(5), crypttab(5), mdadm.conf(5)

that's the whole page, bestie — barrel 0.2.8, dated 2024-07-16. now go partition something responsibly 💜

📦 where this page comes from